Início rápido

Este fluxo cria uma instância, inicia a conexão e envia uma mensagem. Os comandos abaixo representam código de backend ou terminal. Substitua BASE_URL, ADMIN_TOKEN, INSTANCE_TOKEN e o número de destino pelos valores do seu ambiente.

1. Criar uma instância

Esta operação é administrativa e deve acontecer somente no servidor da sua aplicação.

curl -X POST "$BASE_URL/instance/create" \
  -H "Content-Type: application/json" \
  -H "admintoken: $ADMIN_TOKEN" \
  -d '{"name":"minha-instancia"}'

Guarde o campo token retornado. Ele autentica apenas a instância criada.

2. Conectar ao WhatsApp

Sem phone, a API inicia o fluxo por QR Code. Com phone, inicia o fluxo por código de pareamento.

curl -X POST "$BASE_URL/instance/connect" \
  -H "Content-Type: application/json" \
  -H "token: $INSTANCE_TOKEN" \
  -d '{}'

Consulte o estado até receber connected:

curl "$BASE_URL/instance/status" \
  -H "token: $INSTANCE_TOKEN"

Não faça polling agressivo. A interface também pode acompanhar mudanças pelo webhook de connection ou por SSE.

3. Enviar a primeira mensagem

Use o número internacional com código do país, sem +, espaços ou pontuação.

curl -X POST "$BASE_URL/send/text" \
  -H "Content-Type: application/json" \
  -H "token: $INSTANCE_TOKEN" \
  -d '{
    "number": "5511999999999",
    "text": "Olá! Esta mensagem foi enviada pela API."
  }'

4. Receber eventos

Configure um webhook da instância. O filtro wasSentByApi evita que uma automação responda às próprias mensagens e crie um loop.

curl -X POST "$BASE_URL/webhook" \
  -H "Content-Type: application/json" \
  -H "token: $INSTANCE_TOKEN" \
  -d '{
    "enabled": true,
    "url": "https://seu-sistema.example/webhooks/uazapi",
    "events": ["messages", "messages_update", "connection"],
    "excludeMessages": ["wasSentByApi"]
  }'

Próximos passos

  • Consulte Autenticação e segurança antes de expor a integração aos seus clientes.
  • Use a referência OpenAPI para verificar o schema completo de cada operação.
  • Leia Webhooks e callbacks para escolher entre webhook e SSE.
  • Use POST /chat/find e POST /message/find para montar uma experiência de conversas.