Primeiros passos
Conceitos básicos
Convenções que valem para todos os endpoints.
Identificadores#
| Recurso | Tipo do id | Exemplo |
|---|---|---|
| Contato, conversa, mensagem | inteiro | 35 |
| Canal, etiqueta, modelo, sequência, chatbot, webhook | UUID (texto) | 3f6c2a1e-8b4d-4c1a-… |
Telefones#
Envie no formato que tiver: só os dígitos contam. Com 10 ou 11 dígitos e sem +, o número é tratado como brasileiro e ganha +55; com + na frente, vale o código do país informado. As respostas devolvem sempre no formato internacional.
| Você envia | Fica salvo |
|---|---|
11999990000 | +5511999990000 |
(11) 99999-0000 | +5511999990000 |
+351 912 345 678 | +351912345678 |
Contato pelo telefone#
Enviar mensagem, inscrever em sequência e iniciar chatbot aceitam phone_number no lugar de contact_id: se ninguém tiver esse número, o contato é criado (com o name enviado, ou o próprio telefone como nome). E Criar contato é idempotente pelo telefone — repetir a chamada devolve o mesmo contato.
Conversa de destino#
Sem conversation_id, a API usa a conversa mais recente do contato. Se ele ainda não tiver nenhuma, abre uma no canal do channel_id ou, sem ele, no primeiro canal conectado. Sem nenhum canal conectado, a resposta é 422.
Paginação#
Listas grandes (contatos e conversas) usam ?page= a partir de 1 e devolvem total e page. Contatos vêm de 15 em 15; conversas, de 25 em 25. As demais listas voltam completas.
Datas#
created_at e last_activity_at de contatos e conversas são Unix timestamps (segundos). Os demais campos de data, como next_run_at, vêm em ISO 8601 (UTC).
Quem aparece como remetente#
Mensagens enviadas pela API aparecem no chat assinadas como Integração (API), para a equipe saber que não foi um atendente. Chatbots iniciados pela API assinam com o nome do chatbot.