WebSocket de chamadas

Leva o áudio das ligações entre o navegador e a plataforma: faz ligações por troncos SIP e pelo WhatsApp, recebe chamadas, transfere para colegas e filas e mostra quem está disponível.

Conectar

wss://SUA_URL_BASE/ws/call-session?ticket=SEU_TICKET
  • Permissão: call_session:use no workspace.

Ao conectar você recebe conversation:connected com {"feature": "call-session", "workspace_id": string, "user_id": string} e, em seguida, a presença da equipe em call-session:presence.

Áudio

Nos dois sentidos o áudio é PCM de 16 bits little-endian, mono, codificado em base64.

  • Você envia em call_audio, informando sample_rate. O servidor converte 16000, 22050, 24000, 32000, 44100 e 48000 Hz para 8000 Hz; outras taxas são descartadas.
  • Você recebe em call:audio, sempre a 8000 Hz.

Mensagens que você envia

Formato: {"type": "...", "payload": {...}}. Tipos desconhecidos são ignorados.

typepayloadO que faz
start_call{"phone_number": string, "trunk_id"?: string, "whatsapp_phone_id"?: string, "lead_id"?: string, "call_list_item_id"?: string, "request_id"?: string}Faz uma ligação. Com trunk_id sai pelo tronco SIP (exige sip_trunks:call); sem ele, pelo número de WhatsApp em whatsapp_phone_id. O andamento chega em call:status. Veja Ligar para um lead.
end_call{}Desliga a ligação atual.
call_audio{"audio": string, "sample_rate"?: number}Áudio do microfone. Sem resposta.
call:incoming_accept{"offer_id": string}Atende uma chamada oferecida em call:incoming. Precisa vir da mesma conexão que recebeu a oferta.
call:incoming_decline{"offer_id": string, "reason"?: string}Recusa a chamada; ela segue para o próximo atendente.
call:transfer{"target_kind": "member" | "queue", "user_id"?: string, "queue_id"?: string, "notes"?: string}Transfere a ligação atual para um colega (user_id) ou uma fila (queue_id). notes chega a quem atender, até 500 caracteres. O andamento chega em call:transfer_status.
call:transfer_cancel{"call_id": string}Cancela uma transferência para colega ainda tocando; a ligação volta para você.

Para transferir é preciso call_session:transfer e poder atender aquele tipo de ligação. Colegas e filas disponíveis vêm de call-session:presence e de GET /call-queues/transfer-targets.

Ligar para um lead

  • Com lead_id, o lead precisa ser deste workspace, não pode estar bloqueado (lead_blocked) e phone_number precisa ser o WhatsApp dele ou um dos telefones de contato, com ou sem o nono dígito (lead_not_dialable). Uma ligação direta para um lead que pediu para não receber mensagens é permitida; só as listas de ligação o deixam de fora. Se o número for o WhatsApp de outro lead, as regras desse lead também valem: bloqueado dá lead_blocked. A ligação fica registrada no lead: no histórico de chamadas, na gravação e na cobrança.
  • Sem lead_id, o número é procurado entre os leads do workspace e, se for o WhatsApp de um lead, valem as mesmas regras: bloqueado dá lead_blocked. Se a ligação seguir, ela fica registrada nesse lead.
  • call_list_item_id liga o item de uma lista de ligações que você está trabalhando e exige lead_id, o lead do item. A ligação fica registrada como a última do item e renova a reserva dele. O item precisa estar reservado por você (veja POST /call-lists/{listId}/next), ser desse lead e phone_number precisa ser o número do item, senão call_list_item_unavailable. As regras da lista também valem: quem pediu para não receber mensagens não é chamado.
  • Os números e as linhas que podem ligar para um lead vêm de GET /dial-targets?leadId=.

Mensagens que você recebe

typepayloadQuando
conversation:connected{"feature": "call-session", "workspace_id", "user_id"}Ao conectar.
call:status{"status": "ringing" | "answered", "reason"?, "call_id", "phone_number"?, "request_id"?}A ligação está chamando ou foi atendida. Também chega com answered quando você assume uma ligação transferida ou retomada.
call:audio{"audio": string, "sample_rate": 8000}Áudio de quem está do outro lado. Em ligações feitas por você, também traz os tons de progresso padrão brasileiros (ITU-T E.180, 425 Hz): o tom de chamada enquanto o número toca, ou o áudio da própria operadora quando ela envia; e, por 3 segundos antes de call:ended, o tom de ocupado (número ocupado ou recusa) ou de congestionamento (falha).
call:ended{"call_id", "phone_number"?, "reason"?, "duration_seconds": number, "request_id"?}A ligação terminou. reason: ended, failed, busy, no_answer, declined, cancelled, insufficient_balance ou balance_check_error.
call:waiting_slot{"reason": string}Todas as linhas estão ocupadas; a ligação começa quando uma liberar.
call:incomingVeja Chamada oferecidaUma chamada foi oferecida a você.
call:incoming_withdrawn{"offer_id": string, "reason": "no_answer" | "caller_hung_up"}A oferta expirou ou quem ligou desistiu.
call:transfer_statusVeja TransferênciasAndamento da sua transferência.
call-session:presence{"users": [{"user_id", "username"?, "busy": boolean, "on_call"?: boolean, "ringing"?: boolean, "has_browser": boolean}]}Alguém conectou, desconectou, entrou ou saiu de uma ligação. Sem call_session:list_members, a lista traz só você.
telephony:boardVeja Painel de telefoniaJunto com a presença, para quem tem call_session:list_members.
conversation:error{"code": string, "message": string, "entry_id"?: string}Veja Erros.

Chamada oferecida

{
"offer_id": "string",
"call_id": "string",
"workspace_id": "string",
"from_number": "string",
"to_number": "string (opcional)",
"channel": "sip | whatsapp",
"expires_at": "RFC 3339",
"transfer": {
"from_user_id": "string (opcional)",
"from_name": "string (opcional)",
"queue_id": "string (opcional)",
"queue_name": "string (opcional)",
"notes": "string (opcional)"
},
"resume": true
}
  • transfer aparece quando a chamada vem de um colega, de uma fila ou de um fluxo de voz.
  • resume: true indica que é a sua própria ligação voltando depois de a conexão cair (veja abaixo).

Transferências

call:transfer_status chega apenas para quem transferiu:

{
"transfer_id": "string",
"call_id": "string",
"status": "ringing | queued | connected | returned | ended",
"target_user_id": "string (opcional)",
"target_name": "string (opcional)",
"queue_id": "string (opcional)",
"queue_name": "string (opcional)",
"reason": "string (opcional)"
}
  • Para um colega: quem ligou ouve a música de espera e você recebe ringing. Se o colega atender, connected e a ligação sai do seu discador. Se recusar, não atender (20 segundos) ou você cancelar, a ligação volta para você com call:status answered e returned com reason declined, no_answer ou cancelled. Se quem ligou desistir, ended com reason: "caller_hung_up".
  • Para uma fila: você recebe queued e a ligação sai do seu discador na hora. Se ninguém da fila atender até a espera máxima, a ligação toca de novo para você como uma nova call:incoming.
  • Ligações do WhatsApp: a conversa do contato vai junto e passa a ser de quem atender, com as mesmas regras da atribuição manual. Por isso só tocam colegas que podem receber essa conversa; para um colega que não pode, a transferência é recusada com conversation_out_of_reach.

Conexão perdida durante uma ligação

Se a sua conexão cair com uma ligação atendida, quem ligou ouve a música de espera por até 30 segundos. Ao reconectar, você recebe call:incoming com resume: true: aceite para continuar a mesma ligação ou recuse para encerrá-la. Sem reconexão nesse tempo, a ligação é encerrada. Ligações ainda chamando terminam na hora.

Painel de telefonia

{
"workspace_id": "string",
"rev": 0,
"as_of": "RFC 3339",
"capacity": {"used": 0, "max": 0, "pct": 0},
"humans": [{"user_id": "string", "username": "string (opcional)", "state": "free | ringing | on_call", "has_browser": true, "since": "RFC 3339"}],
"queue": {"depth": 0, "available": true},
"online": 0,
"free": 0,
"in_call": 0,
"ringing": 0,
"idle_pct": 0
}

Erros

conversation:error traz code e message. Em erros de chamada oferecida, entry_id é o offer_id; em erros de transferência, é o call_id.

codeSignificado
invalid_payloadMensagem ou payload fora do formato.
missing_fieldsFalta phone_number, offer_id ou call_id, ou lead_id junto com call_list_item_id.
unauthorizedFalta permissão para ligar, para usar o tronco ou para transferir esse tipo de ligação.
already_in_callVocê já está em uma ligação ou atendendo uma chamada.
no_active_callNão há ligação para desligar.
dial_failedNão foi possível iniciar a ligação.
no_call_slotsTodas as linhas ocupadas; tente em instantes.
insufficient_balanceSaldo insuficiente para ligar.
not_configuredOrigem de ligação, ligações para leads ou listas de ligação não configuradas neste servidor.
lead_not_dialableO lead não existe neste workspace, o número não é dele, ou as regras do workspace ou da lista não permitem ligar para ele.
lead_blockedO lead está bloqueado e não recebe ligações.
call_list_item_unavailableO item da lista não está reservado por você, não é do lead ou do número enviados, ou a lista não está ativa ou você não liga nela. Peça o próximo em POST /call-lists/{listId}/next.
whatsapp_permission_requiredO contato não autorizou receber ligações pelo WhatsApp.
trunk_unavailableO tronco não existe, está desativado ou não faz ligações.
trunk_not_registeredO tronco não está registrado no provedor.
invalid_numberO número só pode ter dígitos, *, # e um + no início.
inbound_unavailableChamadas recebidas não estão disponíveis neste servidor.
offer_not_foundA oferta não está mais disponível.
not_for_userA oferta não é sua ou foi enviada para outra conexão.
offer_resolvedA oferta já foi atendida ou recusada.
inbound_failedFalha ao atender.
transfer_unavailableTransferências não estão disponíveis neste servidor.
no_call_to_transferNão há ligação em andamento para transferir.
call_not_foundA ligação já terminou.
not_call_ownerSó quem está na ligação pode transferi-la.
target_unavailableO colega não está livre ou não pode atender esse tipo de ligação.
conversation_out_of_reachEm ligações do WhatsApp, a conversa do contato não pode ser passada para esse colega.
transfer_to_selfNão é possível transferir para você mesmo.
transfer_in_progressEssa ligação já está sendo transferida.
no_transferNão há transferência para cancelar.
queue_not_foundA fila não existe neste workspace.
notes_too_longA nota pode ter até 500 caracteres.
invalid_targetEscolha um colega ou uma fila.
transfer_failedA transferência não pôde ser iniciada.

Autenticação

Abra a conexão com um ticket de tempo real no parâmetro ticket: peça um em POST /v1/realtime/tickets logo antes de conectar. O ticket vale 30 segundos e abre uma única conexão; a cada reconexão, peça outro. Clientes fora do navegador também podem enviar o cabeçalho Authorization: Bearer SEU_ACCESS_TOKEN. O token na URL (?token=) e o cookie accessToken não abrem WebSockets. Um ticket inválido, vencido ou já usado recusa a conexão com realtime_ticket_invalid.

Workspace

Com o ticket, o workspace e o departamento são os do pedido do ticket (cabeçalhos X-Workspace-ID e X-Department-ID): não é preciso repeti-los na URL, e um workspaceId, workspace_id ou departmentId diferente é recusado com workspace_mismatch ou department_mismatch. Com o cabeçalho Authorization, informe o workspace em X-Workspace-ID, como nas rotas HTTP.

Formato das mensagens

Cada quadro de texto carrega um único objeto JSON com o tipo da mensagem. Datas são strings RFC 3339. Antes de abrir o WebSocket, erros de autenticação, workspace e permissão voltam como HTTP comum (401, 400, 403, 429, 501).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
string

Ticket de POST /v1/realtime/tickets (alternativa ao cabeçalho Authorization)

string

Workspace usado na checagem de permissão da conexão

string

Workspace da sessão

Headers
string

Workspace da requisição. Sem ele vale o workspace padrão da pessoa; um workspace do qual ela não participa responde 403 workspace_not_member.

string

Departamento que limita os dados. Quem não participa do departamento recebe 403; donos e administradores escolhem qualquer um.

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
*/*