# Whatix ## Início - [Documentação da API do Whatix](https://docs.whatix.com.br/pt/index.md): API pública de mensageria multicanal: envie mensagens, sincronize contatos e cards, dispare flows. - [Comece em 5 minutos](https://docs.whatix.com.br/pt/quickstart.md): Crie um token, descubra sua conexão e envie a primeira mensagem. - [Autenticação](https://docs.whatix.com.br/pt/autenticacao.md): Header Bearer, escopos por token e os códigos de erro de 401 e 403. - [Erros e limites](https://docs.whatix.com.br/pt/erros-e-limites.md): Formato de erro, catálogo completo de códigos e rate limit de 120 req/min. - [Paginação e filtros](https://docs.whatix.com.br/pt/paginacao-e-filtros.md): pageNumber, pageSize, count, hasMore e filtros de data com offset de fuso. - [Números de telefone](https://docs.whatix.com.br/pt/numeros-de-telefone.md): Formato E.164 sem +, o nono dígito e a validação opcional no WhatsApp. - [Sua instância](https://docs.whatix.com.br/pt/sua-instancia.md): Base URL por tenant, o botão Documentação do painel e a variável instance do playground. - [Changelog](https://docs.whatix.com.br/pt/changelog.md): O que mudou na API do Whatix, versão a versão. ## Guias - [Enviar mensagens](https://docs.whatix.com.br/pt/guias/enviar-mensagens.md): Texto, mídia, template WABA, janela de 24h e como acompanhar a entrega. - [Conversas e mensagens](https://docs.whatix.com.br/pt/guias/conversas-e-mensagens.md): Listar conversas, ler o histórico em ordem, responder com citação e como saber o que mudou. - [Contatos e tags](https://docs.whatix.com.br/pt/guias/contatos-e-tags.md): Upsert idempotente, campos customizados, número imutável e o fluxo de segmentar por tag. - [Cards e pipelines](https://docs.whatix.com.br/pt/guias/cards-e-pipelines.md): Pipeline, etapas e cards; caso guiado de dashboard de marketing; criar card por webhook e mover etapa. - [Disparar flows](https://docs.whatix.com.br/pt/guias/disparar-flows.md): Quando usar, como passar variáveis, a guarda de atendimento humano e a janela de 24h em disparo frio. - [Webhooks de entrada](https://docs.whatix.com.br/pt/guias/webhooks-de-entrada.md): Como um sistema externo entrega dados pro Whatix: URL com hash, fieldMapping e o que acontece com o payload. - [Receita: n8n](https://docs.whatix.com.br/pt/guias/receita-n8n.md): Credencial Bearer, um workflow de reativação completo e como tratar 429 com o nó Wait. ## Referência ### Conversas - [Listar conversas](https://docs.whatix.com.br/pt/referencia/conversas/listar-conversas.md): Lista as conversas (tickets) da sua conta — o histórico de atendimento de cada contato num canal, incluindo as que ainda estão com o chatbot. Ordenadas pela mais recentemente atualizada primeiro. Filtre por `status` (`open`, `pending` ou `closed`, separados por vírgula), `whatsappId` (uma conexão es… ### Mensagens - [Listar mensagens de uma conversa](https://docs.whatix.com.br/pt/referencia/mensagens/listar-mensagens-de-uma-conversa.md): Lista as mensagens de uma conversa (ticket) específica. A página 1 devolve as mensagens MAIS RECENTES (a busca no banco é da mais nova pra mais antiga, e o resultado dessa página é invertido pra ficar em ordem cronológica); pra ler o histórico inteiro, avance `pageNumber` a partir da 1, não pule dir… - [Enviar mensagem numa conversa existente](https://docs.whatix.com.br/pt/referencia/mensagens/enviar-mensagem-numa-conversa-existente.md): Responde numa conversa (ticket) já aberta, usando a mesma conexão do ticket. Envie pelo menos um entre `body` (texto), `medias` (multipart, um ou mais arquivos) ou `templateData` (template aprovado, obrigatório fora da janela de 24h do WABA — depois que o contato responde, a janela reabre por mais 2… - [Enviar mensagem para um número (cria conversa se preciso)](https://docs.whatix.com.br/pt/referencia/mensagens/enviar-mensagem-para-um-número-cria-conversa-se-preciso.md): Envia uma mensagem direto pra um número de telefone, criando o contato e a conversa (ticket) automaticamente quando ainda não existem. A conexão de saída é escolhida nesta ordem: `whatsappId`, se informado; senão `whatsappName`; senão a conexão padrão configurada na sua conta (não por token); senão… - [Consultar status de entrega de uma mensagem](https://docs.whatix.com.br/pt/referencia/mensagens/consultar-status-de-entrega-de-uma-mensagem.md): Consulta o status de entrega de uma mensagem específica pelo id (wamid ou uuid interno) devolvido no envio. O campo `ack` vem cru do WhatsApp: 0 pendente, 1 enviada, 2 recebida pelo servidor, 3 entregue, 4 lida, 5 falhou. Use o `status` (queued, sent, server_ack, delivered, read, failed, received, u… ### Conexões - [Listar conexões (canais) da sua conta](https://docs.whatix.com.br/pt/referencia/conexões/listar-conexões-canais-da-sua-conta.md): Lista as conexões (canais) configuradas na sua conta — WABA, WhatsApp, Facebook ou Instagram — com o `status` atual de cada uma (por exemplo `CONNECTED`). Use pra descobrir o `whatsappId` a passar em POST /v1/messages/send quando quiser escolher a conexão de saída explicitamente, em vez de depender… ### Contatos - [Listar contatos](https://docs.whatix.com.br/pt/referencia/contatos/listar-contatos.md): Lista os contatos da sua conta. Filtre por `searchParam` (nome ou número, busca parcial), `number` (número exato, cobrindo variantes com/sem o 9º dígito BR), `email` (parcial), `channel` (exato, ex.: `whatsapp`) ou `tagId` (IDs separados por vírgula — entra o contato que tiver QUALQUER uma das tags)… - [Criar ou atualizar contato por número (upsert)](https://docs.whatix.com.br/pt/referencia/contatos/criar-ou-atualizar-contato-por-número-upsert.md): Cria o contato se o número ainda não existe na sua conta, ou atualiza o que já existe — a chave de identidade é `number`, não um id. Devolve 201 quando criou e 200 quando atualizou (`created` no corpo confirma qual foi). Só os campos enviados e não vazios são gravados na atualização; `extraInfo` (li… - [Consultar contato por ID](https://docs.whatix.com.br/pt/referencia/contatos/consultar-contato-por-id.md): Consulta um contato específico da sua conta pelo id. É a única operação que devolve `extraInfo` — a listagem GET /v1/contacts não traz esse campo. Contato inexistente ou de outra conta devolve 404 ERR_NO_CONTACT_FOUND, sem distinguir os dois casos. Requer escopo `contacts:read`. - [Atualizar contato](https://docs.whatix.com.br/pt/referencia/contatos/atualizar-contato.md): Atualiza um contato existente. É uma atualização parcial: só os campos enviados no corpo são alterados, os demais permanecem como estão; `extraInfo`, quando enviado, substitui integralmente a lista de campos extras do contato. `number` não pode ser alterado por aqui — é a chave de identidade do cont… - [Sincronizar tags do contato](https://docs.whatix.com.br/pt/referencia/contatos/sincronizar-tags-do-contato.md): Substitui TODA a lista de tags do contato pela lista enviada em `tagIds` — não é um incremento, é uma sincronização completa: para adicionar uma tag preservando as demais, envie o conjunto inteiro (leia as tags atuais em GET /v1/contacts/{contactId} antes, se precisar). Use GET /v1/tags para descobr… - [Listar tags da sua conta](https://docs.whatix.com.br/pt/referencia/contatos/listar-tags-da-sua-conta.md): Lista todas as tags cadastradas na sua conta, sem paginação. Use os ids devolvidos aqui para filtrar contatos por `tagId` em GET /v1/contacts, para sincronizar tags em PUT /v1/contacts/{contactId}/tags e para os filtros `contactTagId`/`notContactTagId` de GET /v1/cards. `kanban` é um id de coluna op… ### Cards - [Listar cards](https://docs.whatix.com.br/pt/referencia/cards/listar-cards.md): "Card" é o nome público do funil de pipeline (venda, suporte, cobrança — o pipeline é genérico). Filtre combinando grupos: pipeline/etapa (`pipelineId`, `stageId`), contato/tag (`contactId`, `contactTagId` — CSV, entra o card cujo contato tem QUALQUER uma das tags; `notContactTagId` — CSV, exclui pe… - [Criar card](https://docs.whatix.com.br/pt/referencia/cards/criar-card.md): Cria um card num pipeline. Informe exatamente um entre `contactId` (contato já existente) e `phone` (cria ou reaproveita o contato pelo número, igual ao upsert de POST /v1/contacts) — nenhum ou os dois juntos devolve 400 ERR_CONTACT_IDENTIFIER_REQUIRED. `pipelineId` é obrigatório: use o `id` devolvi… - [Consultar card por ID](https://docs.whatix.com.br/pt/referencia/cards/consultar-card-por-id.md): Consulta um card específico pelo id, com o mesmo formato devolvido em GET /v1/cards (pipeline, etapa, contato com suas tags, responsável, origem e motivo de perda quando aplicável). Útil pra conferir o estado atual de um card antes de mover a etapa com PATCH /v1/cards/{cardId}/stage. Card inexistent… - [Mover card de etapa](https://docs.whatix.com.br/pt/referencia/cards/mover-card-de-etapa.md): Movimenta o card exatamente como um drag-and-drop no kanban do painel: dispara as mesmas automações de etapa configuradas no pipeline e emite o mesmo evento em tempo real do board — quem estiver com o kanban aberto vê o card mover na hora, sem recarregar a página. `stageId` é obrigatório e precisa p… - [Listar pipelines e suas etapas](https://docs.whatix.com.br/pt/referencia/cards/listar-pipelines-e-suas-etapas.md): Lista os pipelines da sua conta com as etapas já ordenadas (campo `order`, crescente). Cada etapa traz `isFinal` (etapa de encerramento do card) e `isWon` (só relevante quando `isFinal` é true: define se o encerramento é ganho ou perdido) e `probability` (probabilidade associada à etapa). O `id` de… - [Listar motivos de perda](https://docs.whatix.com.br/pt/referencia/cards/listar-motivos-de-perda.md): Lista os motivos de perda cadastrados na sua conta, sem paginação. Cruze o `id` devolvido aqui com o campo `lostReasonId` de GET /v1/cards (filtro) e com o `lostReason` de cada card com `status=lost` pra entender por que os negócios do período foram perdidos. Requer escopo `cards:read`. ### Flows - [Disparar um flow do FlowBuilder para um número](https://docs.whatix.com.br/pt/referencia/flows/disparar-um-flow-do-flowbuilder-para-um-número.md): Dispara um flow (ativo e publicado) num ticket do contato — o disparador das ondas de reativação: consulte os cards perdidos em GET /v1/cards e dispare um flow por lead. Validações síncronas antes do 202: flow executável da conta (404/422), conexão da conta de canal whatsapp/waba (404/422) e guarda… ## OpenAPI Specs - [wapi-v1.pt](/openapi/wapi-v1.pt.json) > The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages. ## Indexes - [English (20 pages)](https://docs.whatix.com.br/_llms/en.md): Documentation for English. - [Spanish (20 pages)](https://docs.whatix.com.br/_llms/es.md): Documentation for Spanish.