Click2Call API

Dispare chamadas telefônicas via Asterisk através de uma requisição HTTP simples.

Visão geral

A API Click2Call recebe uma requisição HTTP GET com os parâmetros da chamada, valida as informações e cria um call file no Asterisk para iniciar a ligação automaticamente.

A chamada é realizada de forma assíncrona — a API confirma que o arquivo foi gerado, mas o status da ligação em si é gerenciado pelo Asterisk.

Autenticação

Toda requisição precisa de dois critérios para ser aceita:

1. IP autorizado

Somente IPs previamente cadastrados no servidor conseguem acessar a rota. Solicite ao responsável técnico a liberação do seu IP de saída.

2. Token no header

Envie o token de autenticação no header X-Call-Token em todas as requisições.

HEADER

X-Call-Token: seu-token-aqui

⚠

Nunca exponha seu token em código client-side, logs ou repositórios públicos.

Endpoint

GET /click2call

ℹ

O endereço base (host + porta) será fornecido pelo responsável técnico da sua integração.

Parâmetros

Todos os parâmetros são enviados via query string e são obrigatórios. Como a transmissão é via URL, todos os valores chegam ao servidor como string — a validação de formato e intervalo é feita server-side.

Parâmetro	Formato esperado	Limite	Descrição
`call_prefix` required	apenas dígitos	máx. 10 chars	Prefixo de discagem no canal (ex: código de saída da central, como `9` ou `0`).
`numero` required	apenas dígitos	máx. 20 chars	Número de telefone a ser chamado. Somente dígitos, sem formatação (ex: `11999990000`).
`exten` required	apenas dígitos	máx. 20 chars	Ramal ou extensão do dialplan para onde a chamada será encaminhada ao ser atendida.
`max_retry` required	dígitos inteiros	0 – 20	Número máximo de tentativas de chamada caso não haja resposta.
`retry_time` required	dígitos inteiros	1 – 300 (seg)	Intervalo em segundos entre cada tentativa de chamada.
`wait_time` required	dígitos inteiros	1 – 300 (seg)	Tempo máximo em segundos de ring antes de considerar a chamada sem resposta.

Respostas

A API retorna sempre Content-Type: application/json com a estrutura:

JSON — ESTRUTURA

{
  "type":    200,
  "message": "Chamada gerada"
}

200

Chamada gerada — O call file foi criado e movido com sucesso. A ligação será iniciada pelo Asterisk em breve.

400

Parâmetro inválido — Um ou mais parâmetros estão ausentes, vazios ou fora do formato/limite esperado. O campo message indica qual parâmetro causou o erro.

403

Acesso negado — IP não autorizado ou header X-Call-Token inválido/ausente.

500

Erro interno — Falha ao gerar ou mover o arquivo de chamada no servidor. Entre em contato com o suporte.

Exemplos de código

Selecione a linguagem e copie o trecho pronto para uso.

SHELL / CURL

curl -X GET \
  "https://seu-servidor.com/click2call?call_prefix=9&numero=11999990000&exten=100&max_retry=3&retry_time=60&wait_time=30" \
  -H "X-Call-Token: seu-token-aqui"

<?php

// Parâmetros da chamada
$params = [
    'call_prefix' => '9',
    'numero'      => '11999990000',
    'exten'       => '100',
    'max_retry'   => 3,
    'retry_time'  => 60,
    'wait_time'   => 30,
];

$url = 'https://seu-servidor.com/click2call?' . http_build_query($params);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Call-Token: seu-token-aqui']);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['message']; // "Chamada gerada"

import requests

params = {
    "call_prefix": "9",
    "numero":      "11999990000",
    "exten":       "100",
    "max_retry":   3,
    "retry_time":  60,
    "wait_time":   30,
}

headers = {"X-Call-Token": "seu-token-aqui"}

r = requests.get(
    "https://seu-servidor.com/click2call",
    params=params,
    headers=headers
)

print(r.json()["message"])  # "Chamada gerada"

const params = new URLSearchParams({
  call_prefix: '9',
  numero:      '11999990000',
  exten:       '100',
  max_retry:   3,
  retry_time:  60,
  wait_time:   30,
});

const res = await fetch(
  `https://seu-servidor.com/click2call?${params}`,
  {
    method: 'GET',
    headers: { 'X-Call-Token': 'seu-token-aqui' },
  }
);

const data = await res.json();
console.log(data.message); // "Chamada gerada"

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://seu-servidor.com/click2call')
uri.query = URI.encode_www_form(
  call_prefix: '9',
  numero:      '11999990000',
  exten:       '100',
  max_retry:   3,
  retry_time:  60,
  wait_time:   30
)

req = Net::HTTP::Get.new(uri)
req['X-Call-Token'] = 'seu-token-aqui'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
data = JSON.parse(res.body)
puts data['message'] # "Chamada gerada"

Erros comuns

Código	Mensagem	Causa provável
400	`Parametro 'X' nao informado`	Campo ausente na query string.
400	`Parametro 'X' fora do limite`	Valor fora do intervalo permitido.
403	`Acesso negado`	IP não liberado ou `X-Call-Token` incorreto/ausente.
500	`O arquivo de chamada nao pode ser gerado`	Problema de permissão no servidor. Contate o suporte.
500	`O arquivo de chamada nao pode ser movido`	Falha ao escrever no diretório do Asterisk. Contate o suporte.