OnZap
Criar conta

Mensagens

Envio de mensagens de todos os tipos, reações, leitura e "digitando…".

Basehttps://app.onzap.io/v1/instances/{instanceId}AuthX-Instance-Token: SEU_TOKEN

Enviar texto

POST/v1/instances/{instanceId}/messages/text
API OnZapAPI oficial

Links ganham prévia automaticamente (linkPreview). Para responder a uma mensagem, informe reply_to com o ID dela.

Na API oficial: até 4096 caracteres; prévia de link só com linkPreview: true. Fora da janela de 24 h desde a última mensagem do cliente, use /messages/template.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

textstringobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
idstringopcional
Pre-generated message id
linkPreviewbooleanopcional
linkPreviewHighQualitybooleanopcional
mentionsarray de stringopcional
Chat IDs to mention in the message. Use ["all"] to mention all participants in a group.
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/text" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "text": "Olá! Seu pedido foi confirmado ✅"
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar imagem

POST/v1/instances/{instanceId}/messages/image
API OnZapAPI oficial

Envie file.url (URL pública) ou file.data (base64) com file.mimetype.

Na API oficial: JPG ou PNG até 5 MB.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

fileobjectobrigatório
captionstringopcional
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
mentionsarray de stringopcional
Chat IDs to mention in the message. Use ["all"] to mention all participants in a group.
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/image" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Confira o catálogo",
    "chatId": "5511999999999",
    "file": {
      "mimetype": "image/jpeg",
      "url": "https://exemplo.com.br/arquivos/catalogo.jpg"
    }
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar arquivo

POST/v1/instances/{instanceId}/messages/file
API OnZapAPI oficial

Qualquer tipo de documento. Envie file.url ou file.data (base64), com file.filename e file.mimetype.

Na API oficial: até 100 MB.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

fileobjectobrigatório
captionstringopcional
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
mentionsarray de stringopcional
Chat IDs to mention in the message. Use ["all"] to mention all participants in a group.
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/file" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Segue o boleto",
    "chatId": "5511999999999",
    "file": {
      "filename": "boleto.pdf",
      "mimetype": "application/pdf",
      "url": "https://exemplo.com.br/arquivos/boleto.pdf"
    }
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar áudio de voz

POST/v1/instances/{instanceId}/messages/voice
API OnZapAPI oficial

Aparece como áudio gravado (ptt). Use OGG/Opus; com convert: true o áudio é convertido automaticamente.

Na API oficial: OGG/Opus até 16 MB.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

convertbooleanobrigatório
Convert the input file to the required format using ffmpeg before sending
fileobjectobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/voice" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "convert": true,
    "file": {
      "mimetype": "audio/mpeg",
      "url": "https://exemplo.com.br/arquivos/audio.mp3"
    }
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar vídeo

POST/v1/instances/{instanceId}/messages/video
API OnZapAPI oficial

MP4 (H.264). Com convert: true o vídeo é convertido automaticamente; asNote: true envia como vídeo redondo.

Na API oficial: MP4 ou 3GP até 16 MB.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

convertbooleanobrigatório
Convert the input file to the required format using ffmpeg before sending
fileobjectobrigatório
asNotebooleanopcional
Send as video note (aka instant or round video).
captionstringopcional
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
mentionsarray de stringopcional
Chat IDs to mention in the message. Use ["all"] to mention all participants in a group.
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/video" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Tutorial",
    "chatId": "5511999999999",
    "convert": true,
    "file": {
      "mimetype": "video/mp4",
      "url": "https://exemplo.com.br/arquivos/video.mp4"
    }
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar figurinha

POST/v1/instances/{instanceId}/messages/sticker
API OnZapAPI oficial

Na API oficial: WEBP (512×512).

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

fileobjectobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/sticker" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "file": {
      "mimetype": "image/webp",
      "url": "https://exemplo.com.br/arquivos/figurinha.webp"
    }
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar link com prévia personalizada

POST/v1/instances/{instanceId}/messages/link-preview
API OnZapAPI oficial

Na API oficial: vira texto com prévia gerada pelo WhatsApp (a imagem personalizada é ignorada).

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

previewobjectobrigatório
preview.descriptionstringobrigatório
preview.titlestringobrigatório
preview.urlstringobrigatório
preview.imageobjectopcional
textstringobrigatório
The text to send. MUST include the URL provided in preview.url
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
linkPreviewHighQualitybooleanopcional
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/link-preview" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "preview": {
      "description": "Até 40% de desconto",
      "title": "Promoção de primavera",
      "url": "https://exemplo.com.br/promo"
    },
    "text": "Veja a promoção: https://exemplo.com.br/promo"
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar botões

POST/v1/instances/{instanceId}/messages/buttons
Só API oficial

Botões de resposta, link, ligação ou copiar código.

Na API oficial: até 3 botões de resposta (20 caracteres) ou um único botão de link; ligação e copiar código só em templates.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

bodystringobrigatório
buttonsarray de objectobrigatório
buttons[].textstringobrigatório
buttons[].typestringobrigatório
Valores:replyurlcallcopy
buttons[].copyCodestringopcional
buttons[].idstringopcional
buttons[].phoneNumberstringopcional
buttons[].urlstringopcional
footerstringobrigatório
headerstringobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
headerImageobjectopcional
phonestringopcional
Apelido de chatId: número com DDI e DDD.
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/buttons" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Podemos confirmar sua consulta de amanhã às 14h?",
    "buttons": [
      {
        "text": "Confirmar",
        "type": "reply"
      },
      {
        "text": "Remarcar",
        "type": "reply"
      }
    ],
    "chatId": "5511999999999",
    "footer": "Clínica Exemplo",
    "header": "Confirmação"
  }'
Resposta

Enviada para a fila. O resultado chega nos eventos `queue.sent` / `queue.failed` e em `GET /queue/{queueId}`.

{
  "attempts": 1,
  "chatId": "[email protected]",
  "createdAt": "2026-09-30T14:05:00Z",
  "delayMs": 3000,
  "error": "número sem WhatsApp",
  "expiresAt": "2026-09-30T14:05:00Z",
  "finishedAt": "2026-09-30T14:05:00Z",
  "id": "qm_01jabcdefghjkmnpqrstvwxyz",
  "messageId": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "position": 1,
  "queued": false,
  "route": "POST /messages/text",
  "status": "queued",
  "typingMs": 2000
}

Enviar lista de opções

POST/v1/instances/{instanceId}/messages/list
API OnZapAPI oficial

Na API oficial: até 10 seções e 10 opções no total; título da opção até 24 caracteres.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

messageobjectobrigatório
message.buttonstringobrigatório
message.sectionsarray de objectobrigatório
message.sections[].rowsarray de objectobrigatório
message.sections[].titlestringobrigatório
message.titlestringobrigatório
message.descriptionstringopcional
message.footerstringopcional
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/list" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "message": {
      "button": "Ver opções",
      "description": "Escolha uma opção",
      "footer": "Pizzaria Exemplo",
      "sections": [
        {
          "rows": [
            {
              "description": "R$ 49,90",
              "rowId": "pizza_margherita",
              "title": "Margherita"
            },
            {
              "description": "R$ 52,90",
              "rowId": "pizza_calabresa",
              "title": "Calabresa"
            }
          ],
          "title": "Pizzas"
        }
      ],
      "title": "Cardápio"
    }
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar enquete

POST/v1/instances/{instanceId}/messages/poll
API OnZap

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

pollobjectobrigatório
poll.multipleAnswersobjectobrigatório
poll.namestringobrigatório
poll.optionsarray de stringobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
idstringopcional
Pre-generated message id
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/poll" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "poll": {
      "multipleAnswers": false,
      "name": "Qual o melhor horário?",
      "options": [
        "Manhã",
        "Tarde",
        "Noite"
      ]
    }
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Votar em enquete

POST/v1/instances/{instanceId}/messages/poll/vote
API OnZap

Corpo (JSON)

pollMessageIdstringobrigatório
The ID of the poll message.
votesarray de array de stringobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
phonestringopcional
Apelido de chatId: número com DDI e DDD.
pollServerIdnumberopcional
Only for Channels - server message id (if known); if omitted, API may look it up in the storage
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/poll/vote" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pollMessageId": "[email protected]_AAAAAAAAAAAAAAAAAAAA",
    "votes": [
      "Awesome!"
    ]
  }'
Resposta

Sucesso

Enviar localização

POST/v1/instances/{instanceId}/messages/location
API OnZapAPI oficial

Na API oficial: mesmo formato.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

latitudenumberobrigatório
longitudenumberobrigatório
titlestringobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
idstringopcional
Pre-generated message id
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/location" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "latitude": -23.5613,
    "longitude": -46.6565,
    "title": "Nossa loja"
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar contato (vCard)

POST/v1/instances/{instanceId}/messages/contact-vcard
API OnZapAPI oficial

Na API oficial: cada contato precisa de fullName e phoneNumber (vCard cru não é aceito).

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

contactsarray de objectobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
idstringopcional
Pre-generated message id
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/contact-vcard" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "contacts": [
      {
        "fullName": "Maria Souza",
        "organization": "Loja Exemplo",
        "phoneNumber": "+55 11 98888-7777",
        "whatsappId": "5511988887777"
      }
    ]
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Encaminhar mensagem

POST/v1/instances/{instanceId}/messages/forward
API OnZap

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

messageIdstringobrigatório
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
idstringopcional
Pre-generated message id
phonestringopcional
Apelido de chatId: número com DDI e DDD.
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/forward" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999",
    "messageId": "[email protected]_3EB0C0A1B2C3D4E5F6"
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Marcar mensagens como lidas

POST/v1/instances/{instanceId}/messages/seen
API OnZapAPI oficial

Marca como lidas (tique azul) as mensagens da conversa.

Na API oficial: marca a mensagem informada (ou a última recebida) como lida.

Corpo (JSON)

chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
messageIdstringopcional
messageIdsarray de stringopcional
participantstringopcional
phonestringopcional
Apelido de chatId: número com DDI e DDD.
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/seen" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999"
  }'
Resposta
{}

Reagir a mensagem

PUT/v1/instances/{instanceId}/messages/reaction
API OnZapAPI oficial

Emoji vazio ("") remove a reação.

Na API oficial: mesmo formato.

Corpo (JSON)

messageIdstringobrigatório
reactionstringobrigatório
Emoji to react with. Send an empty string to remove the reaction
Requisição
curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/reaction" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "[email protected]_3EB0C0A1B2C3D4E5F6",
    "reaction": "👍"
  }'
Resposta

Sucesso · API oficial: mensagem aceita pela Meta

{
  "chatId": "[email protected]",
  "id": "3EB0C0A1B2C3D4E5F6",
  "status": "ok"
}

Gerar novo ID de mensagem

GET/v1/instances/{instanceId}/messages/new-id
API OnZap
Requisição
curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/new-id" \
  -H "X-Instance-Token: $ONZAP_TOKEN"
Resposta
{
  "id": "BBBBBBBBBBBBBBBBB"
}

Enviar evento (agenda)

POST/v1/instances/{instanceId}/messages/event
API OnZap

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

eventobjectobrigatório
event.namestringobrigatório
Name of the event
event.startTimenumberobrigatório
Start time of the event (Unix timestamp in seconds)
event.descriptionstringopcional
Description of the event
event.endTimenumberopcional
End time of the event (Unix timestamp in seconds)
event.extraGuestsAllowedbooleanopcional
Whether extra guests are allowed
event.locationobjectopcional
Location of the event
event.location.namestringobrigatório
Name of the location
chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
phonestringopcional
Apelido de chatId: número com DDI e DDD.
reply_tostringopcional
The ID of the message to reply to - [email protected]_AAAAAAAAAAAAAAAAAAAA
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/event" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "name": "John'\''s Nail Appointment 💅",
      "startTime": 2063137000
    }
  }'
Resposta

Mensagem enviada

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Começar a digitar

POST/v1/instances/{instanceId}/typing/start
API OnZapAPI oficial

Mostra "digitando…" na conversa até POST /typing/stop ou o envio da próxima mensagem.

Na API oficial: só funciona em resposta a uma mensagem recebida nas últimas 24 h; dura até 25 s ou até a resposta.

Corpo (JSON)

chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
phonestringopcional
Apelido de chatId: número com DDI e DDD.
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/typing/start" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999"
  }'
Resposta

Sucesso

Parar de digitar

POST/v1/instances/{instanceId}/typing/stop
API OnZapAPI oficial

Na API oficial: a Meta remove o "digitando…" sozinha ao enviar a resposta.

Corpo (JSON)

chatIdstringopcional
Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid). Pode ser enviado como phone.
phonestringopcional
Apelido de chatId: número com DDI e DDD.
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/typing/stop" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511999999999"
  }'
Resposta

Sucesso

Enviar template

POST/v1/instances/{instanceId}/messages/template
Só API oficial

Única forma de iniciar conversa (ou falar fora da janela de 24 h) na API oficial. Preencha os parâmetros de forma simples (header, body, buttons) ou mande components no formato da Cloud API.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

templatestringobrigatório
Nome do template (também aceito como name).
bodyarray de string | objectopcional
Variáveis do corpo: lista para {{1}}, {{2}}… ou objeto para variáveis nomeadas ({{nome}}).
buttonsarray de objectopcional
buttons[].indexintegerobrigatório
Posição do botão no template (0, 1, 2).
buttons[].couponCodestringopcional
Código do botão copiar código.
buttons[].payloadstringopcional
Payload do botão de resposta rápida.
buttons[].urlstringopcional
Sufixo da URL dinâmica.
chatIdstringopcional
Número com DDI e DDD (5511999999999) ou …@bsuid. Pode ser enviado como phone.
componentsarray de objectopcional
Componentes no formato da Cloud API. Se informado, header, body e buttons são ignorados.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
headerobjectopcional
header.documentstringopcional
URL do documento do cabeçalho.
header.filenamestringopcional
Nome do documento.
header.imagestringopcional
URL da imagem do cabeçalho.
header.textstringopcional
Variável do cabeçalho de texto.
header.videostringopcional
URL do vídeo do cabeçalho.
languagestringopcional
Idioma do template.
phonestringopcional
Apelido de chatId.
reply_tostringopcional
ID da mensagem a responder (citação).
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/template" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": [
      "Maria",
      "#1234"
    ],
    "chatId": "5511999999999",
    "language": "pt_BR",
    "template": "pedido_enviado"
  }'
Resposta

Mensagem aceita pela Meta

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}

Enviar mensagem interativa (formato da Meta)

POST/v1/instances/{instanceId}/messages/interactive
Só API oficial

Para recursos interativos que /messages/buttons e /messages/list não cobrem (ex.: cta_url com cabeçalho, location_request_message, flow). O objeto interactive vai como na Cloud API.

Aceita delayMessage e delayTyping no corpo e o header X-Queue (veja Fila de mensagens na introdução). Enviada na hora, responde 201/200; enfileirada, 202.

Headers

X-Queuestringopcional
true manda este envio para a fila da instância; false envia na hora. Sem o header, vale o modo da instância (delayMessage ou delayTyping no corpo também implicam fila).

Corpo (JSON)

interactiveobjectobrigatório
Objeto interactive da Cloud API.
chatIdstringopcional
Número com DDI e DDD (5511999999999) ou …@bsuid. Pode ser enviado como phone.
delayMessagenumberopcional
Segundos de espera antes de enviar esta mensagem (usa a fila da instância).
delayTypingnumberopcional
Segundos mostrando "digitando…" antes de enviar (usa a fila da instância).
phonestringopcional
Apelido de chatId.
reply_tostringopcional
ID da mensagem a responder (citação).
Requisição
curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/messages/interactive" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "interactive": {}
  }'
Resposta

Mensagem aceita pela Meta

{
  "chatId": "[email protected]",
  "id": "[email protected]_3EB0C0A1B2C3D4E5F6",
  "status": "sent"
}