v2PainelCriar chave

Modo Z-API

Vindo da Z-API? Troque a base URL para https://api.connectdm.app/z-api e a autenticação para o cabeçalho apikey. As rotas de envio e os callbacks seguem o formato da Z-API.

Como o modo Z-API funciona

Base URL: https://api.connectdm.app/z-api. Todas as rotas levam o cabeçalho apikey com a sua chave do ConnectDM. As rotas também aceitam o formato …/instances/:instance/token/:token/…; o token e o cabeçalho Client-Token são ignorados.

Erros voltam como { error, message }. Envio precisa do escopo messages:send; webhooks, de webhooks:write. Reações chegam como ReceivedCallback com o campo reaction.

:instanceId é o nome da instância no ConnectDM. Os callbacks são assinados com x-centralizer-signature, como os demais webhooks.

POSTTexto (Z-API)

/z-api/instances/:instance/send-text

Envia texto no formato Z-API.

phonestringObrigatório
Número com DDI e DDD, só dígitos, ou o grupo (<id>-group ou JID).
messagestringObrigatório
Texto.
delayMessagenumberOpcional
Segundos de espera antes de enviar (0 a 15).
delayTypingnumberOpcional
Segundos mostrando "digitando…" antes de enviar (0 a 15). Vale o maior dos dois.
messageIdstringOpcional
ID da mensagem a responder (citação).
curl -X POST https://api.connectdm.app/z-api/instances/loja/send-text \
  -H "apikey: sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5511999998888",
  "message": "Olá do ConnectDM 👋",
  "delayTyping": 2
}'

POSTImagem (Z-API)

/z-api/instances/:instance/send-image

Envia imagem a partir de URL pública ou base64.

phonestringObrigatório
Número com DDI e DDD, só dígitos, ou o grupo (<id>-group ou JID).
imagestringObrigatório
URL pública ou base64.
captionstringOpcional
Legenda.
delayMessagenumberOpcional
Segundos de espera antes de enviar (0 a 15).
delayTypingnumberOpcional
Segundos mostrando "digitando…" antes de enviar (0 a 15). Vale o maior dos dois.
curl -X POST https://api.connectdm.app/z-api/instances/loja/send-image \
  -H "apikey: sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5511999998888",
  "image": "https://exemplo.com/produto.png",
  "caption": "Confira!"
}'

POSTÁudio (Z-API)

/z-api/instances/:instance/send-audio

Envia áudio como mensagem de voz.

phonestringObrigatório
Número com DDI e DDD, só dígitos, ou o grupo (<id>-group ou JID).
audiostringObrigatório
URL pública ou base64.
delayMessagenumberOpcional
Segundos de espera antes de enviar (0 a 15).
delayTypingnumberOpcional
Segundos mostrando "digitando…" antes de enviar (0 a 15). Vale o maior dos dois.
curl -X POST https://api.connectdm.app/z-api/instances/loja/send-audio \
  -H "apikey: sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5511999998888",
  "audio": "https://exemplo.com/recado.ogg"
}'

POSTDocumento (Z-API)

/z-api/instances/:instance/send-document/:extension

Envia documento; a extensão vai no caminho (pdf, docx, xlsx…).

phonestringObrigatório
Número com DDI e DDD, só dígitos, ou o grupo (<id>-group ou JID).
documentstringObrigatório
URL pública ou base64.
fileNamestringOpcional
Nome exibido; a extensão é adicionada se faltar.
delayMessagenumberOpcional
Segundos de espera antes de enviar (0 a 15).
delayTypingnumberOpcional
Segundos mostrando "digitando…" antes de enviar (0 a 15). Vale o maior dos dois.
curl -X POST https://api.connectdm.app/z-api/instances/loja/send-document/:extension \
  -H "apikey: sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5511999998888",
  "document": "https://exemplo.com/boleto.pdf",
  "fileName": "boleto"
}'

PUTTodos os callbacks de uma vez

/z-api/instances/:instance/token/:token/update-every-webhooks

Usa a mesma URL para os quatro callbacks. Valor vazio remove.

valuestringObrigatório
URL https do seu servidor.
curl -X PUT https://api.connectdm.app/z-api/instances/loja/token/:token/update-every-webhooks \
  -H "apikey: sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "https://seu-app.com/zapi"
}'

PUTCallback por evento

/z-api/instances/:instance/token/:token/update-webhook-received

Uma URL por callback: troque o final por update-webhook-received, update-webhook-delivery, update-webhook-message-status ou update-webhook-connected.

valuestringObrigatório
URL https, ou vazio para remover.
curl -X PUT https://api.connectdm.app/z-api/instances/loja/token/:token/update-webhook-received \
  -H "apikey: sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "https://seu-app.com/zapi/received"
}'

Formato dos callbacks

Todo callback é um POST JSON com o campo type. momment é o horário em milissegundos (grafia da Z-API).

typeQuandoCampos principais
ReceivedCallbackMensagem recebidainstanceId, messageId, phone, chatName, senderName, fromMe, isGroup, participantPhone, status "RECEIVED", momment e o conteúdo (text, image, audio, video, document, sticker, location, contact, reaction, listResponseMessage, buttonsResponseMessage)
DeliveryCallbackMensagem enviada pela instânciaphone, zaapId, messageId, instanceId, momment
MessageStatusCallbackMudança de statusinstanceId, status "SENT" | "RECEIVED" | "READ" | "PLAYED", ids[], phone, isGroup, momment
ConnectedCallbackInstância conectouinstanceId, connected: true, momment
DisconnectedCallbackInstância caiu (vai para a URL de connected)instanceId, momment, error
{
  "type": "ReceivedCallback",
  "instanceId": "loja",
  "messageId": "3EB0A1B2C3D4",
  "phone": "5511999998888",
  "fromMe": false,
  "isGroup": false,
  "senderName": "Maria",
  "status": "RECEIVED",
  "momment": 1763300000000,
  "text": { "message": "Oi, meu pedido chegou?" }
}
© 2026 ConnectDM by Centralizer · Referência da API