WebSocket de conversas

Mantém a caixa de entrada e as conversas abertas atualizadas em tempo real: novas mensagens, leituras, digitação, mudanças de etapa, etiquetas, responsável e status. Também é por ele que o atendente envia mensagens e muda o status da conversa.

Conectar

wss://SUA_URL_BASE/ws/conversations?ticket=SEU_TICKET
ParâmetroObrigatórioDescrição
ticketsim, num navegadorO ticket de POST /v1/realtime/tickets (veja Autenticação). Traz o workspace e o departamento da conexão.
sincenãoO seq do último evento do workspace que você recebeu. Liga os quadros workspace_event (veja Eventos do workspace por seq).
workspaceIdnãoWorkspace da conexão, só com o cabeçalho Authorization. Sem ele, vale o workspace padrão do usuário. Com ticket, se vier, precisa ser o do ticket.
departmentIdnãoDepartamento selecionado; filtra a caixa de entrada. Com ticket, se vier, precisa ser o do ticket.
campaignId + campaignTypenãoAbre a conexão já na caixa de uma campanha. campaignType: whatsapp, unofficial_whatsapp, instagram, facebook ou telegram.
  • Permissão: conversations:read no workspace.
  • O servidor envia um ping a cada 54 segundos; navegadores respondem sozinhos. Sem resposta em 60 segundos, a conexão é encerrada.
  • Mensagens do cliente podem ter até 512 KiB.

Ao conectar, você recebe conversation:connected, depois conversation:connected_users e a primeira página da caixa de entrada em conversation:inbox.

Eventos do workspace por seq

Com since, a conexão também traz o registro de eventos do workspace, o mesmo de GET /v1/events, com as mesmas regras de quem vê cada evento. Primeiro chegam os eventos guardados depois de since, em ordem de seq; depois, cada evento novo assim que é registrado. Exige events:read; sem ela, ou com um since que não é um número inteiro a partir de 0, a conexão é recusada antes de abrir (read_permission_required, events_since_invalid). Guarde o seq do último evento recebido e use-o em since ao reconectar.

typepayload
workspace_eventO evento, no formato de GET /v1/events: {"id", "type", "seq", "createdAt", "workspaceId", "departmentId", "data"}.
resync_required{"code": "resync_required", "message": string, "oldestSeq": number}. O since é mais antigo que a janela de 7 dias: busque o estado atual pela API. Os eventos seguem a partir do oldestSeq.

Uma integração (ticket emitido com uma chave de API) abre só esta conexão e recebe apenas os quadros workspace_event e resync_required; sem since, os eventos começam do início da janela. Ela não aparece entre os usuários conectados e as mensagens que envia são ignoradas. Precisa de conversations:read e events:read.

Mensagens que você envia

Formato: {"type": "...", "payload": {...}}. Tipos desconhecidos recebem conversation:error com code: "unknown_event".

typePermissãopayloadResposta
subscribeconversations:read{"entry_id": string, "entry_type": string, "page_size"?: number}conversation:subscribed e conversation:history. A partir daí você recebe os eventos dessa conversa. page_size padrão 50, máximo 100. Abrir a conversa tira a sua marca pessoal de não lida (chega conversation:personal_mark se havia uma). Logo depois chega conversation:viewers com quem está com a conversa aberta, e todos os inscritos recebem a lista nova.
unsubscribe{"entry_id": string, "entry_type": string}conversation:unsubscribed. Os inscritos que ficam recebem conversation:viewers sem você (quando era a sua última conexão inscrita).
sendconversations:send{"entry_id": string, "entry_type": string, "text"?: string, "media_id"?: string, "media_type"?: "image" | "video" | "audio" | "document" | "sticker", "signed"?: boolean, "request_id": string, "reply_to_message_id"?: string}conversation:message_sent para todos os inscritos e sempre para a conexão que enviou (mesmo sem inscrição, ou quando ela já recebeu a mensagem no histórico), ou conversation:message_error. Informe text ou media_id. request_id (até 128 caracteres, um UUID por envio) torna o envio idempotente: repetir o mesmo request_id na mesma conversa nunca envia de novo; se a mensagem já foi gravada, a resposta é o mesmo conversation:message_sent de antes (mesmo request_id); se o primeiro envio ainda está em andamento, a repetição fica sem resposta e vale a resposta do primeiro. Sem request_id (clientes antigos) não há essa proteção.
send_buttonconversations:send{"entry_id": string, "entry_type": string, "body_text": string, "buttons": [{"id": string, "title": string}], "header_type"?: string, "header_text"?: string, "footer_text"?: string, "request_id": string, "reply_to_message_id"?: string}Igual a send, inclusive a idempotência por request_id. De 1 a 3 botões. Os botões ficam guardados na mensagem e chegam em interactive, para desenhar o balão e para que ela possa ser reenviada.
resend_messageconversations:send{"entry_id": string, "entry_type": string, "message_id": string, "request_id": string}Reenvia uma mensagem que falhou, pelo mesmo caminho de send (saldo, janela, limite mensal, permissões e cobrança valem iguais), com o conteúdo original (texto, mídia, botões e resposta citada). Só vale para mensagem dessa conversa, enviada por um atendente, com deliveryStatus: "failed" e ainda não reenviada; senão conversation:error com not_found, not_allowed ou invalid (falta request_id). O reenvio cria uma mensagem nova: chega conversation:message_updated da mensagem que falhou, agora com resent_as apontando para a nova, e depois conversation:message_sent da nova com o seu request_id. Se o canal recusar, conversation:message_error com esse request_id e code: "send_failed", e a mensagem que falhou fica como estava. Repetir o mesmo request_id responde com a mesma mensagem nova, sem enviar de novo.
react_messageconversations:send{"entry_id": string, "entry_type": string, "message_id": string, "emoji": string, "request_id": string}Reage a uma mensagem no canal; emoji: "" tira a sua reação. Deu certo: conversation:message_updated com a reação em reactions (direction: "outbound", actor_id é você). Falhou: conversation:error, e nada muda.
edit_messageconversations:send{"entry_id": string, "entry_type": string, "message_id": string, "text": string, "request_id": string}Edita o texto de uma mensagem sua. Deu certo: conversation:message_updated com o novo text e edited_at. Falhou: conversation:error, e nada muda.
delete_messageconversations:send{"entry_id": string, "entry_type": string, "message_id": string, "request_id": string}Apaga para todos uma mensagem sua. Deu certo: conversation:message_updated com retracted_at e sem o conteúdo. Falhou: conversation:error, e nada muda.
mark_readconversations:read{"entry_id": string, "entry_type": string, "message_ids": string[]}conversation:read para todos os inscritos. Também tira a sua marca pessoal de não lida dessa conversa (veja Marcas pessoais).
pin_conversationconversations:read{"entry_id": string, "entry_type": string, "pinned": boolean, "request_id": string}Fixa (pinned: true) ou desafixa a conversa só para você. Resposta conversation:personal_mark em todas as suas conexões deste workspace, ou conversation:error.
mark_unreadconversations:read{"entry_id": string, "entry_type": string, "request_id": string}Marca a conversa como não lida só para você. Resposta conversation:personal_mark em todas as suas conexões deste workspace, ou conversation:error.
clear_unread_markconversations:read{"entry_id": string, "entry_type": string, "request_id": string}Tira só a sua marca pessoal de não lida (o desfazer de mark_unread): não marca nenhuma mensagem como lida e não manda confirmação de leitura ao contato. Resposta conversation:personal_mark em todas as suas conexões deste workspace (mesmo quando não havia marca), ou conversation:error.
typingconversations:read{"entry_id": string, "entry_type": string, "is_typing"?: boolean}conversation:typing para os outros inscritos. Sem erros.
request_connected_usersconversations:read{}conversation:connected_users
load_historyconversations:read{"entry_id": string, "entry_type": string, "before": string, "page_size"?: number}conversation:history com mensagens anteriores a before (RFC 3339). has_more diz se há mensagens ainda mais antigas.
load_aroundconversations:read{"entry_id": string, "entry_type": string, "timestamp"?: string, "message_id"?: string, "page_size"?: number}conversation:history em torno de timestamp (RFC 3339) ou da mensagem message_id (informe exatamente um dos dois). Com message_id (por exemplo o replyToMessageId de uma citação que ainda não está carregada), o servidor confere o acesso à conversa, carrega a mensagem e usa o createdAt dela; se ela não existe ou não é dessa conversa, conversation:error com code: "not_found", entry_id e entry_type. has_after diz se há mensagens mais novas depois da página.
load_afterconversations:read{"entry_id": string, "entry_type": string, "after": string, "page_size"?: number}conversation:history com direction: "after" e as mensagens logo depois de after (RFC 3339 com nanossegundos, por exemplo o createdAt da mensagem mais nova que você já tem). has_after: true indica que há mais páginas depois; repita com o createdAt da última mensagem recebida. Serve para recuperar o que chegou durante uma queda de conexão e para voltar ao presente depois de um salto. Mesma checagem de acesso e mesmos limites de page_size de load_history.
request_inbox_pageconversations:read{"page"?: number, "page_size"?: number}conversation:inbox. page_size padrão 20, máximo 50.
search_inboxconversations:readVeja Busca na caixa de entradaconversation:search_results
search_messagesconversations:read{"entry_id": string, "entry_type": string, "query": string, "page"?: number, "page_size"?: number}conversation:search_messages_results
load_entry_matchesconversations:readIgual a search_messages (page_size padrão 10, máximo 50)conversation:entry_matches_results
reopen_windowconversations:reopen{"entry_id": string, "entry_type": string, "template_id": string, "parameters"?: string[], "header_parameters"?: string[], "request_id": string}Envia um template para reabrir a janela de atendimento. parameters são os valores das variáveis do corpo, na ordem em que aparecem; header_parameters, o da variável do texto do cabeçalho. request_id é obrigatório e vale como chave de idempotência na conversa: repetir o mesmo request_id nunca envia nem cobra o modelo duas vezes; sem ele a recusa é idempotency_key_required.
assign_toconversations:assign{"entry_id": string, "entry_type": string, "user_id": string}Sem resposta direta: você recebe conversation:entry_update.
request_funnel_columnconversations:read{"stage_id": string, "page"?: number, "page_size"?: number}conversation:funnel_column
request_funnel_summaryconversations:read{"stage_ids": string[]}conversation:funnel_summary
switch_view{"campaign_id"?: string, "campaign_type"?: string, "whatsapp_campaign_type"?: "standard" | "organic", "container_kind"?: "" | "campaign", "conversation_status"?: "new" | "ongoing" | "finished", "is_group"?: boolean}conversation:view_switched e a primeira página em conversation:inbox. Cancela todas as inscrições em conversas. Com is_group: true a lista é a aba Grupos (veja Grupos); sem ele, as conversas com clientes.
set_conversation_statusconversations:send{"entry_id": string, "entry_type": string, "status": "ongoing" | "finished", "outcome_code"?: string}Sem resposta direta: você recebe conversation:conversation_status_update.

entry_type é o canal da conversa: whatsapp, unofficial_whatsapp, instagram, facebook, telegram, tiktok, mercadolivre, webchat ou email.

Regras de react_message, edit_message e delete_message: o servidor confere o mesmo acesso de send e a regra da ação antes de chamar o canal, então um cliente desatualizado nunca age fora dela. Reagir exige um canal que reage e uma mensagem que o canal identifica e que não foi apagada. Editar exige um canal que edita, uma mensagem só de texto enviada por você e dentro da janela de edição do canal. Apagar exige um canal que apaga, uma mensagem enviada por você e dentro da janela de exclusão do canal. Hoje: WhatsApp por QR Code reage, edita por 15 minutos e apaga por 48 horas; Telegram reage, edita e apaga por 48 horas; Instagram, Facebook e WhatsApp oficial só reagem; o site não tem nenhuma ação. conversation:subscribed traz o que o canal da conversa permite em message_capabilities.

Regras de set_conversation_status: uma conversa volta a new só quando o contato manda uma mensagem nova; uma conversa finalizada só reabre da mesma forma. Se o workspace exige um desfecho, envie outcome_code; sem ele você recebe outcome_required com a lista em outcomes.

Em switch_view com campaign_type: "whatsapp", é preciso whatsapp_campaigns:read; com unofficial_whatsapp e container_kind: "campaign", unofficial_whatsapp_campaigns:read.

Busca na caixa de entrada

Todos os campos de search_inbox são opcionais:

{
"query": "string",
"stage_id": "string",
"stage_name": "string",
"min_message_count": 0,
"max_message_count": 0,
"message_search": "string",
"window_open": true,
"has_unread": true,
"is_group": true,
"channel": "string",
"date_from": "AAAA-MM-DD ou RFC 3339",
"date_to": "AAAA-MM-DD ou RFC 3339",
"conversation_status": "new | ongoing | finished",
"responsible_user_id": "string",
"responsible_unassigned": true,
"responsible_kind": "ai | workflow",
"sort": "recent | waiting",
"label_id": "string",
"personal": "pinned",
"origin": "receptive | campaign | outreach | unknown",
"page": 1,
"page_size": 20
}
  • sort: recent (padrão, a ordem de sempre: a mensagem mais recente primeiro) ou waiting: primeiro as conversas que esperam resposta (as que têm waiting_since), a que espera desde mais cedo no topo, depois as demais pela mais recente. É a mesma regra de waiting_since: conversa finalizada não espera. Outro valor responde conversation:error com invalid_sort.
  • label_id: só conversas com essa etiqueta. Um id ilegível responde invalid_label.
  • is_group: true, busca na aba Grupos (hoje, grupos do WhatsApp não oficial); false, nas conversas com clientes. Sem o campo, vale a aba da sua visão (switch_view). Num canal sem grupos, true não traz nada.
  • personal: sem valor, a sua caixa de entrada (as suas fixadas primeiro, todas as outras em seguida); pinned, só as que você fixou. Outro valor responde invalid_personal.
  • origin: só conversas com essa origem, pela primeira mensagem: receptive (o contato escreveu primeiro), campaign (começou por uma mensagem de campanha), outreach (a equipe, a IA ou um fluxo começou) ou unknown (remetente não registrado). Uma conversa ainda sem origem registrada só aparece sem o filtro. Vale também para os totais e a paginação. Outro valor responde invalid_origin. Cada InboxEntry traz a sua origin quando ela já está registrada.
  • date_from e date_to: um dia AAAA-MM-DD vale o dia inteiro no fuso do workspace (de 00:00 de date_from até 23:59:59 de date_to); um instante RFC 3339 vale como foi enviado. Uma data ilegível ou date_to antes de date_from responde invalid_date; se o fuso do workspace não puder ser lido, date_zone_unreadable, e nada é filtrado em silêncio.
  • Em qualquer sort, as conversas que você fixou vêm primeiro. request_inbox_page, a primeira página ao conectar e switch_view usam a sua caixa de entrada (sem personal) com sort: "recent". As colunas do funil (request_funnel_column, request_funnel_summary) não usam marcas pessoais.

Marcas pessoais

Fixar e marcar como não lida são só seus: ninguém da equipe vê as suas marcas, e elas nunca mostram uma conversa que você não pode ver (valem as mesmas regras de subscribe: departamento, responsável e view_others). Uma conversa que você deixou de ver some das suas marcas.

  • Toda mudança chega em conversation:personal_mark a todas as suas conexões neste workspace (abas e janelas, em qualquer servidor), com mark: null quando não sobrou marca.
  • Abrir a conversa (subscribe) ou mark_read tira a sua marca de não lida. Para desfazer mark_unread use clear_unread_mark, que tira só a marca: mark_read marca as mensagens do contato como lidas e manda a confirmação de leitura a ele.
  • conversation:inbox e conversation:search_results trazem personal_marks com as suas marcas das conversas da página.
  • Os totais por status (conversation_status_counts) são da equipe: as suas marcas não os mudam.

Grupos

Os grupos de WhatsApp ficam sempre na aba Grupos, para todos: as conversas com clientes (a primeira página, request_inbox_page, search_inbox, as colunas do funil e os totais por status) nunca trazem grupos. A aba Grupos é switch_view com is_group: true e mostra todos os grupos, inclusive os finalizados; conversation_status_counts traz o total dela em groups.

  • Cada pessoa pode esconder os grupos (PUT /inbox/preferences com hideGroups: true). Para ela, a aba Grupos e as buscas com is_group: true voltam vazias, e mensagens de grupo não chegam nem tocam aviso. A preferência chega em conversation:inbox_preferences logo depois de conectar e sempre que muda, em todas as suas conexões deste workspace. Quando ela não pode ser lida, vale o padrão: grupos visíveis na aba Grupos.
  • Uma conversa sem a marca de grupo conta como conversa com cliente, para nada sumir por engano.

Recusas de pin_conversation, mark_unread e clear_unread_mark chegam em conversation:error com request_id, entry_id, entry_type e o código: not_allowed (sem conversations:read ou sem acesso à conversa), invalid (falta entry_id, entry_type ou pinned), unsupported (servidor sem marcas pessoais) ou failed (não foi possível gravar).

Mensagens que você recebe

Formato: {"type": "...", "payload": {...}}.

Respostas aos seus pedidos

typepayload
conversation:connected{"user_id": string, "connection_id": string}
conversation:subscribed`{"entry_id", "entry_type", "lead_id"?, "lead_name": string, "lead_number": string, "lead_version": number, "blocked": boolean, "lead_picture": string, "lead_metadata"?: object, "entry_variables"?: string[], "unread_count": number, "automation_enabled": boolean, "window_open": boolean, "window_expires_at"?: string, "window_closed_reason"?: string, "window_closed_detail"?: string, "window_tier"?: "standard"
conversation:unsubscribed{"entry_id": string, "entry_type": string}
conversation:history{"entry_id", "entry_type", "direction": "latest" | "before" | "around" | "after", "messages": Message[], "has_more": boolean, "has_after": boolean, "total": number, "page_size": number}. direction diz qual pedido a página responde: latest (primeira página de subscribe), before (load_history), around (load_around) ou after (load_after). As mensagens vêm sempre da mais antiga para a mais nova. has_more: há mensagens mais antigas que a página (não se aplica a after). has_after: há mensagens mais novas que a página (só em around e after). total vem em latest e around.
conversation:inbox{"entries": InboxEntry[], "personal_marks": PersonalMark[], "page", "page_size", "total_items", "total_pages", "stage_counts"?: object, "conversation_status_counts"?: object, "available_labels"?: Label[]}. personal_marks traz as suas marcas das conversas da página (lista vazia quando não há).
conversation:search_results{"query"?, "filters": object, "entries": InboxEntry[], "personal_marks": PersonalMark[], "page", "page_size", "total_items", "total_pages"}. filters repete os filtros pedidos, inclusive sort, label_id, personal e origin.
conversation:personal_mark{"entry_id", "entry_type", "mark": {"pinned_at"?: string, "unread_marked_at"?: string} | null}. Só para as suas conexões neste workspace: resposta a pin_conversation, mark_unread e clear_unread_mark, e também quando a sua marca muda sozinha (abrir ou ler a conversa). mark: null: nenhuma marca.
conversation:search_messages_results{"entry_id", "entry_type", "query", "messages": Message[], "page", "page_size", "total_items", "total_pages"}
conversation:entry_matches_results{"entry_id", "entry_type", "query", "matches": MatchedMessage[], "page", "page_size", "total_items", "total_pages"}
conversation:window_reopened{"entry_id", "entry_type", "request_id"?, "template_id", "message_id"}
conversation:funnel_column{"stage_id", "entries": InboxEntry[], "page", "page_size", "total_items", "total_pages"}
conversation:funnel_summary{"columns": [{"stage_id": string, "total_items": number}]}
conversation:view_switched{"view_mode": "global" | "campaign", "campaign_id"?, "campaign_type"?, "whatsapp_campaign_type"?, "container_kind"?, "conversation_status"?, "is_group"?: boolean}. is_group: true: a visão é a aba Grupos.
conversation:inbox_preferences{"hide_groups": boolean}. As suas preferências da caixa de entrada neste workspace: chega logo depois de conectar e sempre que mudam (em qualquer servidor). Com hide_groups: true, esconda a aba Grupos.
conversation:connected_users{"users": [{"user_id", "workspace_id", "campaign_id", "campaign_type", "campaign_name"?, "view_mode", "username"?, "email"?, "connected_at"}]}. Também chega sozinho quando alguém entra, sai ou troca de visão. Você só vê colegas dos seus departamentos, salvo se tiver acesso a todo o workspace.
conversation:message_error{"request_id", "entry_id", "entry_type", "error": string, "code"?: string}. Falha de send, send_button ou do envio de resend_message.
conversation:errorVeja Erros.

Eventos das conversas em que você se inscreveu

typepayloadQuando
conversation:message{"entry_id", "entry_type", "message": Message}Chegou ou foi enviada uma mensagem (contato, IA, fluxo, agendamento, chamadas).
conversation:message_sent{"request_id", "entry_id", "entry_type", "message": Message}Um atendente enviou uma mensagem. Chega para todos os inscritos.
conversation:message_updated{"entry_id", "entry_type", "message": Message}Uma mensagem já entregue mudou: foi editada ou apagada (pelo contato ou pela equipe), recebeu ou perdeu uma reação, ganhou a transcrição do áudio, ou falhou e foi reenviada (resent_as). Traz a mensagem inteira no mesmo formato de conversation:message; substitua a que você tem pelo id. Chega só para quem está inscrito na conversa.
conversation:read{"entry_id", "entry_type", "message_ids": string[], "read_by": string, "read_at": string}Mensagens foram marcadas como lidas.
conversation:typing{"entry_id", "entry_type", "user_id"?, "is_typing": boolean}Um colega está digitando.
conversation:message_status{"entry_id", "entry_type", "message_id", "status": "sent" | "delivered" | "read" | "failed"}O canal confirmou a entrega.
conversation:analysis_update{"entry_id", "entry_type", "analysis": Analysis | null, "pending": boolean}A análise da conversa mudou.
conversation:ad_origin{"entry_id", "entry_type", "ad_origin": AdOrigin}O contato chegou por um anúncio (WhatsApp, Instagram ou Facebook). Só a primeira vez: o anúncio de origem não muda.
conversation:conversation_status_update{"entry_id", "entry_type", "status", "close_source"?, "close_reason"?, "close_outcome"?, "closed_at"?}O status da conversa mudou.
conversation:viewers{"entry_id", "entry_type", "viewers": [{"user_id": string, "name": string}]}Quem está com a conversa aberta agora mudou: alguém se inscreveu, cancelou a inscrição ou desconectou (em qualquer servidor). Também chega logo depois do seu subscribe, com a lista atual. Traz todos os inscritos, inclusive você (filtre o seu user_id); cada pessoa aparece uma vez, mesmo com várias abas ou janelas destacadas. name é o nome de usuário (texto vazio quando não foi encontrado). A lista é a fotografia completa: substitua a anterior.
conversation:note{"entry_id", "entry_type", "note": Note}Alguém da equipe gravou uma nota interna na conversa (POST /conversations/{entryType}/{entryId}/notes).
conversation:note_deleted{"entry_id", "entry_type", "note_id": string}O autor apagou uma nota interna; tire-a da tela.

Uma mesma mensagem chega uma vez só por conexão: como conversation:message ou como conversation:message_sent.

Eventos do workspace

Chegam mesmo sem inscrição, para quem tem acesso à conversa e está na visão correspondente:

typepayloadQuando
conversation:entry_update{"entry": InboxEntry, "silent"?: boolean, "alert"?: boolean, "unlisted"?: boolean}Nova mensagem, envio, troca de responsável, status ou etapa. silent: true indica atualização sem novidade para o atendente. alert: true só vem numa mensagem nova do cliente e só para quem deve ser avisado: o responsável humano; ninguém quando um agente ou fluxo é o responsável ou quando a distribuição automática vai entregar a conversa; na fila manual, quem pode pegá-la. Toque o som e mostre o aviso só quando alert vier. unlisted: true vem com alert quando a conversa é de outra aba (um grupo enquanto você vê os clientes, ou o contrário): avise, mas não ponha a conversa na lista atual. Quem escondeu os grupos não recebe nada de grupos.
conversation:assigned_to_you{"entry": InboxEntry, "assigned_at": string}Uma conversa passou a ser sua pela distribuição automática, por um colega, por uma transferência ou por um agente ou fluxo. Não chega quando você mesmo a pega. Chega uma vez por atribuição, em todas as suas conexões deste workspace.
conversation:conversation_status_counts_update{"counts": {"new": number, "ongoing": number, "finished": number, "groups"?: number}}Os totais por status mudaram. new, ongoing e finished contam só conversas com clientes; groups conta todos os grupos (a aba Grupos) e só vem quando a visão inclui um canal com grupos.
conversation:stage_update{"entry_id", "entry_type", "stage": Stage | null}A etapa da conversa mudou.
conversation:label_update{"entry_id", "entry_type", "labels": Label[]}As etiquetas mudaram.
conversation:entry_removed{"entry_id", "entry_type", "reason": "assigned"}A conversa foi para outra pessoa e você não a vê mais.
audience:analyzed{"workspaceId", "source", "accountId", "containerId", "items": CommentAnalyzed[], "more": number}Um lote de comentários foi analisado. Só para quem tem audience:read.
notification:created{"workspaceId", "item": {"id", "category", "severity", "title", "body", "imageUrl"?, "actionUrl"?, "actionLabel"?, "createdAt"}}Uma notificação nova chegou para você neste workspace (a mesma forma de GET /notifications). Só para os destinatários dela. Atualize o contador com GET /notifications/summary.
conversation:lead_update{"leadId": string, "version": number, "fields": string[]}Um lead mudou (edição, nome, bloqueio, responsável, opt-out, família, anonimização). Traz só os nomes dos campos, nunca os valores; um campo personalizado aparece como customFields.<chave>, e anonymized diz que o lead foi anonimizado e não existe mais (a nova leitura responde 404): busque o lead de novo por uma rota que você pode usar (GET /leads/{id} com leads:read, ou a própria conversa). Chega para quem tem leads:read e para quem está inscrito em uma conversa desse lead. Use version no If-Match da próxima edição.
conversation:leads_bulk_update{"runId": string}Um lote de uma ação em massa sobre leads (classificar, atribuir, bloquear) foi gravado. Chega uma vez por lote, só para quem tem leads:read; não traz ids de leads nem valores. Recarregue a lista e consulte o andamento em GET /leads/actions/{runId}.

Chat da equipe

Conversas internas entre colegas (veja a seção Chat da equipe da API). Os eventos chegam só para quem participa da conversa, em todas as suas conexões deste workspace, em qualquer servidor. Os comandos são pela API HTTP; o socket só traz os eventos e a digitação. Quem não tem conversations:read não abre este socket: atualize GET /team-chat/summary a cada minuto. Ao reconectar, recupere o que perdeu com GET /team-chat/threads e, em cada conversa aberta, GET /team-chat/threads/{id}/messages com after_seq igual ao maior seq que você já tem.

typeDireçãopayloadQuando
team_chat_typingvocê envia{"thread_id": string}Você está digitando. Envie no máximo um a cada 3 segundos. Precisa participar da conversa; recusas não têm resposta.
team_chat:messagevocê recebe{"thread_id", "message": TeamChatMessage}Mensagem nova, inclusive as suas (para as suas outras abas), as de sistema e as agendadas no momento do envio.
team_chat:message_updatedvocê recebe{"thread_id", "message": TeamChatMessage}Uma mensagem foi editada (edited_at) ou apagada (deleted_at, sem texto).
team_chat:readvocê recebe{"thread_id", "user_id", "seq"}Alguém leu a conversa até seq (confirmação de leitura; quando é você, sincroniza as suas abas).
team_chat:threadvocê recebe{"thread_id"}A conversa mudou (criada com você, título, participantes, silenciada): busque GET /team-chat/threads/{id}.
team_chat:thread_removedvocê recebe{"thread_id"}Você saiu ou foi tirado do grupo: remova a conversa da tela.
team_chat:typingvocê recebe{"thread_id", "user_id"}Alguém está digitando. Some sozinho depois de 5 segundos sem um novo aviso.
team_chat:scheduledvocê recebe{"thread_id", "scheduled": TeamChatScheduled}Uma mensagem que você agendou mudou: criada, alterada, cancelada, enviada ou falhou (failure_reason). Só para o autor.

TeamChatMessage: id, thread_id, seq (ordem na conversa, sem buracos), author_id, author_name, kind (text | system), body, event? (só em system: created | renamed | members_added | member_removed | member_left), subject_ids (quem a mensagem de sistema afeta), reply_to_id?, mentions, client_id?, created_at, edited_at?, deleted_at?. TeamChatScheduled: id, thread_id, body, mentions, reply_to_id?, send_at, status (pending | sent | canceled | failed), failure_reason?, sent_message_id?, created_at, updated_at.

Tipos usados nas mensagens

InboxEntry: entry_id, entry_type, campaign_id?, campaign_name?, lead_id?, lead_name?, lead_number?, lead_version?, blocked, lead_picture?, is_group?, lead_metadata?, entry_variables?, unread_count, last_message_preview?, last_message_at, last_message_type?, last_message_sender?, last_message_sender_avatar?, last_message_sender_kind? (contact | human | ai | workflow | campaign | system | external: quem mandou a última mensagem, para o cliente nomear o remetente no idioma de quem lê; external é uma mensagem enviada pela conta fora da plataforma, no app do próprio canal ou no celular; ausente em mensagens antigas sem remetente gravado), last_message_author? (groups: name of the member who sent the last message), last_message_from_us? (groups: the last message was ours), last_customer_message_at? (quando o contato escreveu por último, em todos os canais), last_agent_message_at? (quando a equipe, uma IA, um fluxo ou uma campanha escreveu por último), waiting_since? (RFC 3339: desde quando o contato espera resposta, a primeira mensagem dele depois da última resposta da equipe, de uma IA ou de um fluxo, inclusive a digitada no celular fora da plataforma; campanha e aviso do sistema não são resposta; ausente quando ninguém espera ou a conversa está finalizada; finalizar a conversa encerra a espera e a próxima mensagem do contato começa outra), window_open, window_expires_at?, window_closed_reason?, window_closed_detail? (o mesmo estado da janela que conversation:subscribed informa, em todos os canais; sem como confirmar o estado, a linha vem fechada com channel_unavailable), business_phone_id?, assigned_user_id?, assigned_username?, automation_enabled, stage?: Stage, labels?: Label[], available_stages?: Stage[], matched_messages?: MatchedMessage[], total_matches?, latest_analysis?: Analysis, analysis_phase?: "awaiting" | "queued", live_read?: LiveRead, conversation_status?: new | ongoing | finished, close_source?: human | ai | system, close_reason?: manual | customer_idle | ai_resolved | max_age | workflow, closed_at?, close_outcome?, ai_handler?: AIHandler.

Message (chaves em camelCase): id, entryId, entryType, channel, messageType, direction?: INBOUND | OUTBOUND, from, to, text, mediaId?, mediaType?, read, readAt?, readBy?, whatsappMessageId?, externalMessageId?, replyToMessageId?, deliveryStatus?: sent | delivered | read | failed, senderName?, senderAvatar?, sentVia?: business_app, sentBy: {"kind": "contact" | "human" | "ai" | "workflow" | "campaign" | "external" | "system", "id": string}, metadata?, location?: {"latitude": number, "longitude": number, "name"?: string, "address"?: string, "candidate": boolean}, createdAt, updatedAt. Em snake_case: transcript? (transcrição de um áudio recebido; hoje só no WhatsApp oficial; o text do áudio continua sendo o marcador [Áudio]), edited_at? (a mensagem foi editada, pelo contato ou por um atendente; text já é o novo texto), retracted_at? (a mensagem foi apagada, pelo contato ou por um atendente: text vem vazio e transcript, mediaId, mediaType, media, metadata e location não vêm), reactions?: Reaction[] (ausente quando não há reações), sender_user_id? (o usuário da equipe que enviou a mensagem; ausente quando não foi um atendente), client_request_id? (o request_id do envio de um atendente, para casar a mensagem com o balão pendente), resent_as? (esta mensagem falhou e foi reenviada como a mensagem com esse id; esconda esta e mostre a nova), interactive?: Interactive, interactive_reply?: InteractiveReply.

Interactive (mensagem enviada com opções, em qualquer canal e por qualquer remetente: fluxo, agente de IA, atendente, campanha ou modelo do WhatsApp oficial; traz só o que o contato recebeu, depois dos limites do canal): {"kind": "buttons" | "list" | "cta_url" | "template", "header"?: {"type": "text" | "image" | "video" | "document", "text"?: string, "media_url"?: string}, "body": string, "footer"?: string, "button_label"?: string (o rótulo que abre a lista), "sections"?: [{"title"?: string, "rows": [{"id": string, "title": string, "description"?: string}]}], "buttons"?: [{"kind": "reply" | "url" | "phone" | "copy_code" | "flow", "id"?: string, "title": string, "url"?: string, "phone"?: string, "code"?: string}], "template_name"?: string}. InteractiveReply (resposta do contato que escolheu uma opção; replyToMessageId aponta para a mensagem com as opções quando o canal informa): {"kind": "button" | "list" | "template_button" | "option" | "quick_reply" | "postback", "option_id": string, "title"?: string}.

location aparece em toda mensagem de localização (WhatsApp oficial e coexistência, Telegram), recebida ou enviada, para desenhar o cartão do mapa. candidate: true marca a localização que o lead mandou, dentro do Brasil, que pode virar a posição dele por POST /leads/{id}/location-candidates/{messageId}/accept (exige leads:update; o servidor confere de novo a conversa e o lead).

Valores de messageType: user_message, ai_response, tool_call, tool_result, audio, system, media, operator, template, call_permission_request, call_permission_granted, call_permission_rejected, call_received, call_answered, call_missed, call_ended, story_reply, story_mention, reaction, unsupported, post_share, sticker, link_share.

Stage: stage_id, name, color?. Label: label_id, name, color?.

PersonalMark: entry_id, entry_type, pinned_at? (fixada por você), unread_marked_at? (marcada por você como não lida). Só as marcas de quem pediu.

Note (nota interna, só da equipe; nunca vai para o contato, a IA, a análise, os fluxos, as exportações ou o chat do site): id, entry_id, entry_type, author_id, author_name, body, mentions: string[] (IDs de usuários mencionados; lista vazia quando não há), created_at. A mesma forma de GET /conversations/{entryType}/{entryId}/notes.

Reaction: emoji, direction: inbound | outbound (inbound é do contato, outbound é nossa), actor_id? (quem reagiu: o identificador do contato no canal ou o usuário da equipe), at. Há no máximo uma reação de cada contato e uma só nossa (outbound), porque a conta da empresa reage uma vez por mensagem: uma reação nova substitui a anterior do mesmo lado e remover a reação a tira da lista. Na reação outbound, actor_id é o atendente que reagiu pelo sistema; reações feitas direto no celular chegam sem actor_id. Mensagens antigas do Instagram e do Facebook com a reação guardada no formato anterior chegam na mesma forma.

MatchedMessage: message_id, text, from, message_type, channel, created_at, position, page.

AIHandler: kind, agent_id?, agent_name?, agent_avatar?, agent_active, workflow_id?, workflow_name?, workflow_run_id?, run_status?, current_node_id?, current_node_type?.

AdOrigin (camelCase): o primeiro anúncio que trouxe o contato. adId?, platform?: facebook | instagram, title?, sourceUrl?, image?: {"url", "mimeType"?, "layout": {"width"?, "height"?, "thumbhash"?}} (cópia guardada pela plataforma), arrivedAt.

PageOrigin (camelCase): a página do site que trouxe o contato (o código (ref XXXXX) na primeira mensagem). projectId, projectName? (nome da página; sem o campo quando a página foi apagada), route (caminho da página, como /oferta), url? (endereço público da página, só quando ela está no ar com um endereço ativo), reference, arrivedAt. Só vem quando a página é do mesmo workspace da conversa.

LiveRead (camelCase): interest?, disposition?, sentiment?, qualification?, nextAction?, language?, attendanceQuality, certainty?: object, decidedAt.

Analysis (camelCase): análise da conversa com id, status, sentiment?, intent?, interest?, productInterest?, disposition?, qualification?, nextAction?, summary?, attendanceQuality?, messageCount?, requiresAction, excerpt, analyzedAt? e demais campos de identificação (workspaceId, source, accountId, containerId, subjectId, createdAt, updatedAt).

CommentAnalyzed (camelCase): commentId, subjectKind, authorExternalId, authorHandle?, stance?, sentiment?, intent?, topicKey?, severity, requiresAction, isSpam, excerpt, interest?, productInterest?, disposition?, qualification?, nextAction?, summary?, occurredAt, analyzedAt.

Valores de window_closed_reason: expired, no_inbound, contact_blocked, session_down, account_restricted, reply_revoked e channel_unavailable.

Datas são strings RFC 3339.

Erros

conversation:error traz {"code": string, "message": string}; recusas de reopen_window, react_message, edit_message, delete_message, resend_message, pin_conversation, mark_unread e clear_unread_mark também trazem request_id, entry_id e entry_type; em mudanças de status, também entry_id, entry_type, status, previous_status e outcomes ([{"code", "label", "isDurable", "position"}]).

codeSignificado
forbiddenFalta permissão, a campanha é de outro workspace ou a regra de status não permite a mudança. Se o acesso ao workspace for revogado, a conexão é encerrada logo depois.
unauthorizedVocê não tem acesso a essa conversa, ou o responsável escolhido não pode recebê-la.
unknown_eventtype desconhecido.
invalid_payloadO payload não tem o formato esperado.
missing_fieldsFalta um campo obrigatório.
missing_contentMensagem sem texto nem mídia.
invalid_buttonsÉ preciso de 1 a 3 botões.
invalid_entry_typeentry_type inválido.
invalid_timestampData fora do formato RFC 3339.
invalid_statusStatus diferente de new, ongoing ou finished.
invalid_sort, invalid_personal, invalid_labelsearch_inbox com sort, personal ou label_id inválido.
invalid_date, date_zone_unreadablesearch_inbox com uma data ilegível, um período invertido, ou sem o fuso do workspace para aplicar as datas.
invalid_campaign_type, invalid_container_kind, invalid_whatsapp_campaign_typeFiltro de visão inválido.
not_foundCampanha não encontrada, ou mensagem que não existe ou não é dessa conversa.
not_configuredO recurso não está disponível neste servidor.
not_allowedAções sobre mensagens: falta conversations:send ou acesso à conversa, a mensagem não é sua, já foi apagada ou não pode receber essa ação (por exemplo, editar uma mídia ou reenviar uma mensagem que não falhou). Marcas pessoais: falta conversations:read ou acesso à conversa.
invalidAções sobre mensagens: falta entry_id, entry_type, message_id, o texto da edição ou o request_id do reenvio, ou o request_id passa de 128 caracteres. Marcas pessoais: falta entry_id, entry_type ou pinned.
unsupportedO canal da conversa não tem essa ação. Em marcas pessoais: o servidor não oferece marcas pessoais.
window_expiredA janela do canal para essa ação já passou, ou a janela de atendimento está fechada.
failedO canal recusou a ação ou ela não pôde ser gravada; nada mudou na conversa. Em marcas pessoais: a marca não pôde ser gravada.
outcome_requiredEscolha um desfecho (lista em outcomes) para finalizar.
outcome_unknownO desfecho não existe no workspace (lista em outcomes).
history_error, inbox_error, search_error, fetch_error, template_send_failed, assign_failed, internal_errorFalha ao processar o pedido; tente de novo.
lead_opted_out, lead_blocked, within_spam_window, window_already_open, insufficient_balance, monthly_send_cap_reached, pricing_unavailable, quote_out_of_range, template_not_sendable, template_phone_mismatch, invalid_phone, phone_not_connected, send_in_progress, idempotency_key_required, billing_unavailable, conversation_not_foundRecusa de reopen_window, com request_id (o mesmo do pedido), entry_id e entry_type: o mesmo código que POST /whatsapp/outreach/conversations responde para a mesma recusa (inclusive forbidden e not_found para número ou modelo). Uma falha sem motivo conhecido chega como template_send_failed.
send_outcome_unknownreopen_window sem resposta do WhatsApp: o modelo pode ter sido entregue e cobrado. Confira a conversa antes de enviar de novo; não repita automaticamente. Traz request_id, entry_id e entry_type.

Códigos de conversation:message_error: unauthorized, not_configured, send_failed, internal_error, media_not_sendable (a mídia não é um envio desta conversa nem da biblioteca do workspace, ou é imagem de nota interna; a mesma resposta vale para uma mídia que não existe) e, no e-mail, email_balance_insufficient (o saldo da carteira não cobre o envio), email_attachment_blocked, email_attachment_too_large, email_domain_checking (o domínio do destinatário ainda está sendo verificado; nada foi cobrado, tente de novo em instantes), email_domain_unknown, email_disposable_address e email_no_mail_domain (a higiene de lista recusou o destinatário; nada foi cobrado).

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

string

Departamento selecionado; filtra a caixa de entrada

integer

seq do último evento do workspace recebido; liga os quadros workspace_event

string

Abre a conexão na caixa de uma campanha (junto com campaignType)

string
enum

Canal da campanha

Allowed:
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:
*/*