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:useno 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, informandosample_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.
| type | payload | O 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) ephone_numberprecisa 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_idliga o item de uma lista de ligações que você está trabalhando e exigelead_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 ephone_numberprecisa ser o número do item, senãocall_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
| type | payload | Quando |
|---|---|---|
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:incoming | Veja Chamada oferecida | Uma 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_status | Veja Transferências | Andamento 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:board | Veja Painel de telefonia | Junto 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
}transferaparece quando a chamada vem de um colega, de uma fila ou de um fluxo de voz.resume: trueindica 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,connectede a ligação sai do seu discador. Se recusar, não atender (20 segundos) ou você cancelar, a ligação volta para você comcall:statusansweredereturnedcomreasondeclined,no_answeroucancelled. Se quem ligou desistir,endedcomreason: "caller_hung_up". - Para uma fila: você recebe
queuede 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 novacall: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.
| code | Significado |
|---|---|
invalid_payload | Mensagem ou payload fora do formato. |
missing_fields | Falta phone_number, offer_id ou call_id, ou lead_id junto com call_list_item_id. |
unauthorized | Falta permissão para ligar, para usar o tronco ou para transferir esse tipo de ligação. |
already_in_call | Você já está em uma ligação ou atendendo uma chamada. |
no_active_call | Não há ligação para desligar. |
dial_failed | Não foi possível iniciar a ligação. |
no_call_slots | Todas as linhas ocupadas; tente em instantes. |
insufficient_balance | Saldo insuficiente para ligar. |
not_configured | Origem de ligação, ligações para leads ou listas de ligação não configuradas neste servidor. |
lead_not_dialable | O 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_blocked | O lead está bloqueado e não recebe ligações. |
call_list_item_unavailable | O 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_required | O contato não autorizou receber ligações pelo WhatsApp. |
trunk_unavailable | O tronco não existe, está desativado ou não faz ligações. |
trunk_not_registered | O tronco não está registrado no provedor. |
invalid_number | O número só pode ter dígitos, *, # e um + no início. |
inbound_unavailable | Chamadas recebidas não estão disponíveis neste servidor. |
offer_not_found | A oferta não está mais disponível. |
not_for_user | A oferta não é sua ou foi enviada para outra conexão. |
offer_resolved | A oferta já foi atendida ou recusada. |
inbound_failed | Falha ao atender. |
transfer_unavailable | Transferências não estão disponíveis neste servidor. |
no_call_to_transfer | Não há ligação em andamento para transferir. |
call_not_found | A ligação já terminou. |
not_call_owner | Só quem está na ligação pode transferi-la. |
target_unavailable | O colega não está livre ou não pode atender esse tipo de ligação. |
conversation_out_of_reach | Em ligações do WhatsApp, a conversa do contato não pode ser passada para esse colega. |
transfer_to_self | Não é possível transferir para você mesmo. |
transfer_in_progress | Essa ligação já está sendo transferida. |
no_transfer | Não há transferência para cancelar. |
queue_not_found | A fila não existe neste workspace. |
notes_too_long | A nota pode ter até 500 caracteres. |
invalid_target | Escolha um colega ou uma fila. |
transfer_failed | A 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).
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||