Primeira chamada

Do zero até listar canais, criar um contato e enviar uma mensagem pela API pública.

Este passo a passo vai do nada até uma mensagem entregue no WhatsApp do seu cliente. São quatro chamadas, escritas em curl. Traduza para a linguagem que você usa.

Antes de começar

Você precisa de duas informações, as duas descritas em Autenticação:

o número da conta, algo como 12345
a chave de API, em Configurações > Integrações > Chave de API

Guarde as duas em variáveis para não repeti-las:

export SUNCHAT_BASE="https://api-publica.sunchat.com.br"
export SUNCHAT_CONTA="12345"
export SUNCHAT_CHAVE="sua-chave-aqui"

1. Confirme que a chave funciona

O endpoint de etiquetas é o teste mais barato. Ele lê pouco e existe em toda conta.

curl -s "$SUNCHAT_BASE/v1/etiquetas?pageSize=1" \
  -H "X-Ambiente: $SUNCHAT_CONTA" \
  -H "X-Authorization: X-Chave-Api $SUNCHAT_CHAVE"

Resposta esperada:

{
  "Items": [
    { "Id": "3c9e6679-7425-40de-944b-e07fc1f90ae7", "Nome": "Cliente VIP" }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalItems": 14,
  "TotalPages": 14,
  "HasNext": true,
  "HasPrevious": false
}

Se vier 401 com corpo vazio, o problema está nos cabeçalhos. O checklist de 401 resolve os casos mais comuns.

2. Descubra o ID do canal

Mensagem sempre sai por um canal. Liste os canais da conta para achar o ID do canal de WhatsApp:

curl -s "$SUNCHAT_BASE/v1/canais" \
  -H "X-Ambiente: $SUNCHAT_CONTA" \
  -H "X-Authorization: X-Chave-Api $SUNCHAT_CHAVE"

Guarde o Id do canal que você vai usar. Ele é fixo, então descubra uma vez, salve na sua configuração e não repita esta chamada em produção.

export SUNCHAT_CANAL="3f2a9c10-5b7e-4d81-a6f3-9e0c1b2d4a58"

3. Crie um contato

Telefone é o único campo obrigatório. Use o formato internacional, só dígitos: 55 mais DDD mais número.

curl -s -X POST "$SUNCHAT_BASE/v1/contatodechat" \
  -H "X-Ambiente: $SUNCHAT_CONTA" \
  -H "X-Authorization: X-Chave-Api $SUNCHAT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "Nome": "Maria Souza",
    "Telefone": "5511987654321",
    "Email": "maria@exemplo.com.br",
    "IdCanal": "'"$SUNCHAT_CANAL"'"
  }'

A resposta é 201 Created com o contato criado, já com o Id gerado.

Já tem esse contato na base? Use PUT /v1/contatodechat, que localiza o contato pelo telefone e atualiza, sem precisar do Id. Se o telefone não existir, ele devolve 404. Essa é a base do laço de sincronização: tenta o PUT, e cria com POST só quando vier 404.

4. Envie a mensagem

O canal vai no caminho. O destinatário e o texto, no corpo.

curl -s -X POST "$SUNCHAT_BASE/v1/message/SendText/$SUNCHAT_CANAL" \
  -H "X-Ambiente: $SUNCHAT_CONTA" \
  -H "X-Authorization: X-Chave-Api $SUNCHAT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "Number": "5511987654321",
    "Text": "Olá, Maria! Seu pedido saiu para entrega."
  }'

A mensagem entra na conversa do contato e aparece na caixa de entrada do time, como qualquer outra.

Enviar mensagem por WhatsApp tem regras da própria Meta. Fora da janela de 24 horas desde a última mensagem do cliente, só passa template aprovado, por POST /v1/message/SendTemplate/{idCanal}. O guia do canal WhatsApp oficial explica a janela.

Variações úteis

Objetivo	Endpoint
Enviar imagem, vídeo ou documento	`POST /v1/message/SendMedia/{idCanal}`
Enviar áudio (mensagem de voz)	`POST /v1/message/SendAudio/{idCanal}`
Enviar template do WhatsApp Business	`POST /v1/message/SendTemplate/{idCanal}`
Registrar nota interna, sem enviar ao cliente	Qualquer um dos acima com `"Nota": true`

Próximos passos

Recursos

Os 28 recursos da API e o que cada um cobre.

Paginação e filtros

Como percorrer listas grandes sem perder ou repetir registros.

Erros

O que cada código de resposta significa e como tratar.

Enumerações

O significado de cada valor numérico dos campos de enumeração.