Enviando mensagens

O envio é assíncrono. A API coloca a mensagem na fila e responde 202 na hora; o envio de fato acontece em seguida. O resultado chega pelos webhooks message.sent e message.status.

Para enviar imagem, vídeo, áudio ou documento, veja Envio de mídia.

Texto

POST /v1/instances/{instanceId}/messages/text

Campo	Tipo	Descrição
to	texto, obrigatório	Telefone de quem vai receber (veja abaixo)
text	texto, obrigatório	Mensagem, de 1 a 10.000 caracteres
quotedMessageId	texto, opcional	Identificador da mensagem a responder, com até 128 caracteres

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/messages/text \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999", "text": "Seu pedido saiu para entrega." }'

Resposta (202):

{ "id": "…", "status": "queued" }

Guarde o id: é com ele que você liga a resposta aos webhooks. Campos que não estão na tabela são recusados com 400.

O telefone

A API ignora tudo que não for dígito, então +55 (11) 99999-9999 vale. Com 10 ou 11 dígitos (DDD e número), ela acrescenta o 55. O resultado precisa ter 12 ou 13 dígitos; fora disso a resposta é 400 com invalid_phone.

Para responder a uma mensagem recebida, use o waMessageId dela em quotedMessageId.

Acompanhando o resultado

Configure os webhooks e você recebe:

1. message.sent, quando a mensagem saiu da fila e foi enviada. O corpo traz o id devolvido no 202, o waMessageId e o type.
2. message.status, a cada mudança de situação da mensagem. O status é sent, delivered, read ou failed.

Se o envio falhar depois de aceito, o message.status vem com status: "failed" e um campo error:

error	O que aconteceu
number_not_on_whatsapp	O telefone não tem WhatsApp
send_failed	O envio falhou depois de 3 tentativas
instance_suspended	A instância foi suspensa antes do envio
expired	A mensagem ficou mais de 7 dias na fila (por exemplo, com a instância desconectada)
media_too_large	O arquivo baixado da url passou do limite de tamanho
media_download_failed	A API não conseguiu baixar a mídia da url

Fila de envio

Operação	Rota	O que faz
Ver a fila	GET /queue	Devolve { "waiting": n, "delayed": n }: mensagens esperando a vez e mensagens com nova tentativa agendada
Limpar a fila	DELETE /queue	Remove as mensagens que ainda não foram enviadas e devolve { "removed": n }

Mensagens já enviadas não são afetadas pela limpeza. As removidas não são enviadas.

Verificar se o número tem WhatsApp

POST /v1/instances/{instanceId}/contacts/check aceita de 1 a 50 telefones por chamada e exige a instância conectada:

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/contacts/check \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "phones": ["5511999999999", "5511888888888"] }'

A resposta é uma lista com um item por telefone: { "phone": "...", "exists": true, "jid": "..." }. Quando o número não tem WhatsApp, vem exists: false e não há jid.

Erros de envio

Status	Código	Quando
400	validation_error	Campo ausente, grande demais ou fora da tabela; a mensagem lista os campos
400	invalid_phone	Telefone fora das regras acima
402	instance_suspended	Instância suspensa ou com pagamento pendente
409	instance_not_connected	Instância desconectada, quando a opção disableQueueWhenDisconnected está ligada em PATCH /settings
422	contact_opted_out	O contato pediu para não receber mensagens

Com disableQueueWhenDisconnected desligada (o padrão), a API aceita a mensagem mesmo com a instância desconectada e ela espera na fila.

Dica

Evite enviar para quem não conversa com você. Mensagens em massa para desconhecidos aumentam o risco de bloqueio do número pelo WhatsApp. Ative o descadastro para respeitar quem pede para sair.