API v1REST · JSON · Webhooks assinados

konversa-api

Mensagens e ligações de voz do WhatsApp no mesmo número, com um QR Code só. Envie texto, mídia e menus, gerencie grupos, faça ligações com gravação e URA, e receba tudo no seu webhook.

46 rotas

mensagens, mídia, grupos e perfil

10 eventos

no webhook ou em tempo real

Ligações com áudio

WebRTC, gravação, URA e conferência

Seus exemplos, prontos para colar

Preencha e todos os códigos desta página já saem com a sua URL e o seu token. Fica só neste navegador.

Início rápido

  1. 1

    Receba suas credenciais

    Ao contratar, você recebe o token da sua instância e o webhook_secret. Guarde os dois no servidor, nunca no navegador ou no app.

    Sobre o token
    Terminal
    # .env do seu servidor
    KONVERSA_API_URL=https://api.konversa.email:8443
    KONVERSA_TOKEN=kv_…
    KONVERSA_WEBHOOK_SECRET=whsec_…
  2. 2

    Conecte o WhatsApp

    Peça o pareamento e leia o QR de /v1/status em Aparelhos conectados, no celular.

    Ver a rota
    Terminal
    curl -X POST "https://api.konversa.email:8443/v1/connect" \
      -H "Authorization: Bearer SEU_TOKEN"
    
    curl "https://api.konversa.email:8443/v1/status" \
      -H "Authorization: Bearer SEU_TOKEN"
  3. 3

    Mande a primeira mensagem

    Pronto. As respostas do cliente chegam no seu webhook como evento message.

    Ver a rota
    Terminal
    curl -X POST "https://api.konversa.email:8443/v1/messages/text" \
      -H "Authorization: Bearer SEU_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "to": "5544999998888", "text": "Olá! 👋" }'

Autenticação

Toda requisição leva o cabeçalho Authorization: Bearer <token> com o token da sua instância. Cada token vale para um número de WhatsApp: com mais de um número, você recebe um token para cada.

Token da instância

Entregue uma vez, junto com o webhook_secret, quando a instância é criada. Ele abre todas as rotas /v1/* deste número.

Token vazou?

Peça um token novo ao suporte: o antigo para de valer na hora. A URL do webhook você troca sozinho, com PATCH /v1/webhook.

Chame a API sempre a partir do seu servidor. Um token exposto no navegador ou no app deixa qualquer pessoa mandar mensagens pelo seu número.

Respostas e erros

As respostas são JSON. Em caso de sucesso, o resultado vem em data; em caso de falha, a mensagem vem em error, em português, pronta para mostrar.

Sucesso
{
  "data": {
    "id": "3EB0C431C26A1916E07A",
    "to": "5544999998888@s.whatsapp.net",
    "timestamp": "2026-10-21T14:32:10Z"
  }
}
Erro
{
  "error": "este número não tem WhatsApp"
}
StatusQuando acontece
400JSON inválido ou campo obrigatório faltando. A mensagem diz qual.
401Token ausente ou inválido.
403Link de mídia assinado inválido ou expirado.
404Número sem WhatsApp, ligação, instância ou mídia não encontrada.
422Áudio da URA em formato errado (use WAV PCM 16 bits).
429Limite de ligações simultâneas, conexões demais em /v1/events ou bloqueio de contato novo ativo. Não insista.
502O WhatsApp recusou ou não respondeu. Tente de novo em instantes.
503A instância não está conectada. Confira /v1/status.

Telefones: mande só dígitos com DDI (5544999998888). Números brasileiros com ou sem o nono dígito são resolvidos automaticamente.

Conexão

Conecte o número lendo o QR Code no WhatsApp do celular (Aparelhos conectados) ou com o código de pareamento. Acompanhe o estado por GET /v1/status ou pelo evento connection.

Estado da conexão

GET/v1/status

Estado atual: disconnected, connecting, qr, connected ou logged_out. Durante o pareamento, qr traz o conteúdo do QR Code.

reach_out_locked: true quer dizer que o WhatsApp bloqueou temporariamente mensagens e ligações para contatos novos. Até reach_out_locked_until, fale só com quem já conversa com você: insistir pode levar a banimento.

privacy_ready: false logo após conectar é normal. Espere ficar true antes de mandar mensagem para contatos novos.

curl "https://api.konversa.email:8443/v1/status" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "id": "inst_8f3a2c",
    "name": "Comercial",
    "state": "connected",
    "jid": "5544999998888:12@s.whatsapp.net",
    "phone": "5544999998888",
    "push_name": "Minha Loja",
    "privacy_ready": true,
    "reach_out_locked": false
  }
}

Conectar

POST/v1/connect

Reconecta uma sessão existente ou inicia o pareamento. Sem phone, gera o QR Code (veja em /v1/status). Com phone, devolve um código de 8 dígitos para digitar no celular.

Corpo (JSON)

phonestring

Número a parear por código, com DDI. Omita para usar QR Code.

curl -X POST "https://api.konversa.email:8443/v1/connect" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "5544999998888"
}'
Resposta200 OK
{
  "data": {
    "status": {
      "id": "inst_8f3a2c",
      "name": "Comercial",
      "state": "qr",
      "privacy_ready": true,
      "reach_out_locked": false
    },
    "pair_code": "K7QM-2XPA"
  }
}

Desconectar

POST/v1/logout

Sai do WhatsApp e apaga a sessão. Para voltar, é preciso parear de novo.

curl -X POST "https://api.konversa.email:8443/v1/logout" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "id": "inst_8f3a2c",
    "name": "Comercial",
    "state": "logged_out",
    "privacy_ready": true,
    "reach_out_locked": false
  }
}

Mensagens

Todo envio devolve o id da mensagem: guarde-o para responder, reagir, editar ou apagar depois. Números brasileiros com ou sem o nono dígito são resolvidos automaticamente.

Enviar texto

POST/v1/messages/text

Envia uma mensagem de texto. Aceita a formatação do WhatsApp (*negrito*, _itálico_, ~riscado~).

Corpo (JSON)

tostringobrigatório

Telefone com DDI (5544999998888), JID de contato (…@s.whatsapp.net) ou de grupo (…@g.us).

textstringobrigatório

Conteúdo da mensagem.

quoteobject

Responde citando uma mensagem: { id, sender?, text? }. sender é obrigatório em grupos.

mentionsstring[]

JIDs mencionados (grupos). Coloque @5544… no texto para aparecer destacado.

forwardedboolean

Mostra a etiqueta “Encaminhada” para quem recebe.

curl -X POST "https://api.konversa.email:8443/v1/messages/text" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "5544999998888",
  "text": "Olá! Seu pedido *#1042* saiu para entrega 🚚"
}'
Resposta200 OK
{
  "data": {
    "id": "3EB0C431C26A1916E07A",
    "to": "5544999998888@s.whatsapp.net",
    "timestamp": "2026-10-21T14:32:10Z"
  }
}

Enviar mídia

POST/v1/messages/media

Imagem, vídeo, áudio, documento ou figurinha, por URL pública ou em base64.

Corpo (JSON)

tostringobrigatório

Telefone com DDI (5544999998888), JID de contato (…@s.whatsapp.net) ou de grupo (…@g.us).

typestringobrigatório

image, video, audio, document ou sticker.

urlstring

Link do arquivo. Use url ou base64.

base64string

Arquivo em base64 (aceita data URI).

mime_typestring

Tipo do arquivo. Se omitido, é detectado.

captionstring

Legenda (imagem, vídeo e documento).

file_namestring

Nome mostrado no documento.

pttboolean

Áudio como mensagem de voz (aquela com a onda).

quoteobject

Responde citando uma mensagem: { id, sender?, text? }. sender é obrigatório em grupos.

mentionsstring[]

JIDs mencionados (grupos). Coloque @5544… no texto para aparecer destacado.

forwardedboolean

Mostra a etiqueta “Encaminhada” para quem recebe.

O corpo da requisição aceita até 96 MB. O WhatsApp aceita vídeos de até 64 MB.

curl -X POST "https://api.konversa.email:8443/v1/messages/media" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "5544999998888",
  "type": "document",
  "url": "https://seusite.com/boletos/1042.pdf",
  "file_name": "Boleto 1042.pdf",
  "caption": "Segue o boleto 😉"
}'
Resposta200 OK
{
  "data": {
    "id": "3EB0C431C26A1916E07A",
    "to": "5544999998888@s.whatsapp.net",
    "timestamp": "2026-10-21T14:32:10Z"
  }
}

Enviar contato

POST/v1/messages/contact

Envia um ou mais cartões de contato (vCard).

Corpo (JSON)

tostringobrigatório

Telefone com DDI (5544999998888), JID de contato (…@s.whatsapp.net) ou de grupo (…@g.us).

contactsobject[]obrigatório

Lista de { name, phone }.

quoteobject

Responde citando uma mensagem: { id, sender?, text? }. sender é obrigatório em grupos.

curl -X POST "https://api.konversa.email:8443/v1/messages/contact" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "5544999998888",
  "contacts": [
    {
      "name": "Suporte",
      "phone": "5544988887777"
    }
  ]
}'
Resposta200 OK
{
  "data": {
    "id": "3EB0C431C26A1916E07A",
    "to": "5544999998888@s.whatsapp.net",
    "timestamp": "2026-10-21T14:32:10Z"
  }
}

Enviar menu

POST/v1/messages/menu

Menu interativo: até 3 opções viram botões; de 4 a 10 viram uma lista que abre num botão. Botões também podem copiar um texto (código, Pix copia e cola).

Corpo (JSON)

tostringobrigatório

Telefone com DDI (5544999998888), JID de contato (…@s.whatsapp.net) ou de grupo (…@g.us).

textstringobrigatório

Texto principal.

footerstring

Rodapé em letra menor.

button_textstring

Lista: texto do botão que abre as opções.

optionsobject[]obrigatório

De 1 a 10 itens { id, title, description?, copy? }.

options[].copystring

Transforma a opção em botão de copiar: o toque copia este texto (até 2048 caracteres) para o cliente, sem enviar resposta. Só no modo botões (até 3 opções).

A escolha do cliente chega no evento message com type: "reply" e reply.id igual ao id da opção.

Botão de copiar: { "id": "copiar", "title": "Copiar código", "copy": "482913" }. Pode ser misturado com botões de resposta no mesmo menu; com 4 ou mais opções (lista) a API recusa.

curl -X POST "https://api.konversa.email:8443/v1/messages/menu" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "5544999998888",
  "text": "Como podemos ajudar?",
  "footer": "Responda tocando numa opção",
  "options": [
    {
      "id": "pedido",
      "title": "Meu pedido"
    },
    {
      "id": "financeiro",
      "title": "Financeiro"
    },
    {
      "id": "humano",
      "title": "Falar com alguém"
    }
  ]
}'
Resposta200 OK
{
  "data": {
    "id": "3EB0C431C26A1916E07A",
    "to": "5544999998888@s.whatsapp.net",
    "timestamp": "2026-10-21T14:32:10Z"
  }
}

Reagir

POST/v1/messages/reaction

Reage a uma mensagem com um emoji. Emoji vazio remove a reação.

Corpo (JSON)

chatstringobrigatório

JID da conversa onde está a mensagem.

message_idstringobrigatório

ID da mensagem alvo.

from_meboolean

true se a mensagem alvo foi enviada por esta instância.

senderstring

Em grupos, JID de quem enviou a mensagem alvo.

emojistringobrigatório

Emoji da reação ("" remove).

curl -X POST "https://api.konversa.email:8443/v1/messages/reaction" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat": "5544999998888@s.whatsapp.net",
  "message_id": "3EB0C431C26A1916E07A",
  "emoji": "❤️"
}'
Resposta200 OK
{
  "data": {
    "id": "3EB0C431C26A1916E07A",
    "to": "5544999998888@s.whatsapp.net",
    "timestamp": "2026-10-21T14:32:10Z"
  }
}

Editar

POST/v1/messages/edit

Troca o texto de uma mensagem enviada por esta instância. O WhatsApp permite editar até 15 minutos após o envio.

Corpo (JSON)

chatstringobrigatório

JID da conversa.

message_idstringobrigatório

ID da mensagem enviada.

textstringobrigatório

Novo texto.

curl -X POST "https://api.konversa.email:8443/v1/messages/edit" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat": "5544999998888@s.whatsapp.net",
  "message_id": "3EB0C431C26A1916E07A",
  "text": "Seu pedido *#1042* foi entregue ✅"
}'
Resposta200 OK
{
  "data": {
    "id": "3EB0C431C26A1916E07A",
    "to": "5544999998888@s.whatsapp.net",
    "timestamp": "2026-10-21T14:32:10Z"
  }
}

Apagar para todos

POST/v1/messages/revoke

Apaga a mensagem para todos. Mensagens de outras pessoas só podem ser apagadas em grupos onde a instância é admin.

Corpo (JSON)

chatstringobrigatório

JID da conversa onde está a mensagem.

message_idstringobrigatório

ID da mensagem alvo.

from_meboolean

true se a mensagem alvo foi enviada por esta instância.

senderstring

Em grupos, JID de quem enviou a mensagem alvo.

curl -X POST "https://api.konversa.email:8443/v1/messages/revoke" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat": "5544999998888@s.whatsapp.net",
  "message_id": "3EB0C431C26A1916E07A",
  "from_me": true
}'
Resposta200 OK
{
  "data": {
    "id": "3EB0C431C26A1916E07A",
    "to": "5544999998888@s.whatsapp.net",
    "timestamp": "2026-10-21T14:32:10Z"
  }
}

Marcar como lida

POST/v1/messages/read

Envia a confirmação de leitura (os dois tiques azuis).

Corpo (JSON)

chatstringobrigatório

JID da conversa.

idsstring[]obrigatório

IDs das mensagens lidas.

senderstring

Em grupos, JID de quem enviou.

curl -X POST "https://api.konversa.email:8443/v1/messages/read" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat": "5544999998888@s.whatsapp.net",
  "ids": [
    "3EB0C431C26A1916E07A"
  ]
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Digitando / gravando

POST/v1/presence

Mostra “digitando…” ou “gravando áudio…” na conversa. Bom antes de respostas automáticas.

Corpo (JSON)

tostringobrigatório

Telefone com DDI (5544999998888), JID de contato (…@s.whatsapp.net) ou de grupo (…@g.us).

statestringobrigatório

composing, recording ou paused.

curl -X POST "https://api.konversa.email:8443/v1/presence" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "5544999998888",
  "state": "composing"
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Baixar mídia recebida

GET/v1/media/{id}

Arquivo de uma mensagem recebida, já descriptografado. O evento message traz em media.url um link assinado que abre sem token. A resposta é o próprio arquivo, não JSON.

Parâmetros do caminho

idstringobrigatório

ID da mídia (parte final de media.url).

Query

instance, exp, sigstring

Link assinado: com estes três parâmetros a rota dispensa o token.

A mídia fica disponível pelo tempo de KONVERSA_MEDIA_TTL (24 h por padrão). Baixe e guarde no seu storage.

curl "https://api.konversa.email:8443/v1/media/3A5F2B8E1C04D7A96E21" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -o arquivo
Resposta200 OK
<arquivo binário · Content-Type: image/jpeg>

Contatos e perfil

Valide números antes de disparar e mantenha nome e foto do perfil em dia.

Quem tem WhatsApp

POST/v1/contacts/check

Confere de 1 a 50 números e devolve o JID real de cada um (com o nono dígito resolvido).

Corpo (JSON)

phonesstring[]obrigatório

De 1 a 50 telefones com DDI.

curl -X POST "https://api.konversa.email:8443/v1/contacts/check" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "phones": [
    "5544999998888",
    "554433221100"
  ]
}'
Resposta200 OK
{
  "data": [
    {
      "phone": "5544999998888",
      "exists": true,
      "jid": "5544999998888@s.whatsapp.net"
    },
    {
      "phone": "554433221100",
      "exists": false
    }
  ]
}

Foto do contato

GET/v1/contacts/picture

Link temporário da foto de perfil de um contato ou grupo. Vazio quando não há foto ou ela é privada.

Query

tostringobrigatório

Telefone ou JID.

curl "https://api.konversa.email:8443/v1/contacts/picture?to=5544999998888" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "url": "https://pps.whatsapp.net/v/t61.24694-24/…"
  }
}

Importar etiquetas

POST/v1/labels/sync

Busca de novo as etiquetas do WhatsApp Business (e quem está em cada uma) e as respostas rápidas. Chegam em seguida pelo evento chat_sync (label_edit, label_chat com full_sync: true, e quick_reply).

curl -X POST "https://api.konversa.email:8443/v1/labels/sync" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Criar ou editar etiqueta

POST/v1/labels

Cria, renomeia ou apaga uma etiqueta do WhatsApp Business. color é o índice da cor (0 a 19).

Corpo (JSON)

label_idstringobrigatório

Id da etiqueta (o mesmo de label_edit).

namestringobrigatório

Nome.

colornumber

Cor, de 0 a 19.

deletedboolean

true apaga.

curl -X POST "https://api.konversa.email:8443/v1/labels" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label_id": "12",
  "name": "Pago",
  "color": 5
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Etiquetar conversa

POST/v1/chats/label

Coloca ou tira a conversa de uma etiqueta.

Corpo (JSON)

chatstringobrigatório

Telefone ou JID.

label_idstringobrigatório

Id da etiqueta.

labeledbooleanobrigatório

true coloca, false tira.

curl -X POST "https://api.konversa.email:8443/v1/chats/label" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat": "5544999998888",
  "label_id": "12",
  "labeled": true
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Arquivar conversa

POST/v1/chats/archive

Arquiva ou desarquiva a conversa no WhatsApp do número.

Corpo (JSON)

chatstringobrigatório

Telefone ou JID.

archivedbooleanobrigatório

true arquiva.

curl -X POST "https://api.konversa.email:8443/v1/chats/archive" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat": "5544999998888",
  "archived": true
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Fixar conversa

POST/v1/chats/pin

Fixa ou desafixa a conversa.

Corpo (JSON)

chatstringobrigatório

Telefone ou JID.

pinnedbooleanobrigatório

true fixa.

curl -X POST "https://api.konversa.email:8443/v1/chats/pin" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat": "5544999998888",
  "pinned": true
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Silenciar conversa

POST/v1/chats/mute

Silencia até end_ms (milissegundos desde 1970; -1 = sempre) ou reativa.

Corpo (JSON)

chatstringobrigatório

Telefone ou JID.

mutedbooleanobrigatório

false reativa.

end_msnumber

Fim do silêncio; -1 = sempre.

curl -X POST "https://api.konversa.email:8443/v1/chats/mute" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "chat": "5544999998888",
  "muted": true,
  "end_ms": -1
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Agenda do número

GET/v1/contacts

Contatos que o número conhece: nome salvo na agenda do celular (saved), nome de perfil e nome comercial. Só números, sem grupos.

curl "https://api.konversa.email:8443/v1/contacts" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": [
    {
      "phone": "5544999998888",
      "name": "Cliente Exemplo",
      "push_name": "Cliente",
      "saved": true
    }
  ]
}

Recado e empresa

GET/v1/contacts/info

Recado do contato e se é uma conta comercial (com o nome verificado, quando houver).

Query

tostringobrigatório

Telefone ou JID.

curl "https://api.konversa.email:8443/v1/contacts/info?to=5544999998888" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "about": "Disponível",
    "is_business": true,
    "verified_name": "Loja Exemplo"
  }
}

Meu perfil

GET/v1/profile

Telefone, nome e foto do número conectado.

curl "https://api.konversa.email:8443/v1/profile" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "phone": "5544999998888",
    "name": "Minha Loja",
    "picture_url": "https://pps.whatsapp.net/v/t61.24694-24/…"
  }
}

Alterar nome

POST/v1/profile/name

Troca o nome exibido do número conectado.

Corpo (JSON)

namestringobrigatório

Novo nome.

curl -X POST "https://api.konversa.email:8443/v1/profile/name" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Minha Loja"
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Alterar foto

POST/v1/profile/picture

Troca a foto de perfil. Use uma imagem quadrada em JPEG.

Corpo (JSON)

urlstring

Link da imagem. Use url ou base64.

base64string

Imagem em base64.

curl -X POST "https://api.konversa.email:8443/v1/profile/picture" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://seusite.com/logo.jpg"
}'
Resposta200 OK
{
  "data": {
    "id": "1729520530"
  }
}

Grupos

Liste os grupos do número, gerencie participantes e configure o grupo. Para alterar, a instância precisa ser admin.

Listar grupos

GET/v1/groups

Todos os grupos de que o número participa, com os participantes.

curl "https://api.konversa.email:8443/v1/groups" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": [
    {
      "jid": "120363025246125486@g.us",
      "name": "Clientes VIP",
      "topic": "Novidades em primeira mão",
      "announce": false,
      "locked": true,
      "join_approval_required": false,
      "is_admin": true,
      "participants": [
        {
          "jid": "5544999998888@s.whatsapp.net",
          "phone": "5544999998888",
          "is_admin": true,
          "is_super_admin": true,
          "name": "Minha Loja"
        }
      ]
    }
  ]
}

Consultar grupo

GET/v1/groups/{jid}

Dados e participantes de um grupo.

Parâmetros do caminho

jidstringobrigatório

JID do grupo (…@g.us).

curl "https://api.konversa.email:8443/v1/groups/120363025246125486%40g.us" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "jid": "120363025246125486@g.us",
    "name": "Clientes VIP",
    "announce": false,
    "locked": true,
    "join_approval_required": false,
    "is_admin": true,
    "participants": [
      {
        "jid": "5544999998888@s.whatsapp.net",
        "phone": "5544999998888",
        "is_admin": true,
        "is_super_admin": true
      }
    ]
  }
}

Participantes

POST/v1/groups/{jid}/participants

Adiciona, remove, promove a admin ou rebaixa participantes. A resposta traz o resultado por pessoa.

Parâmetros do caminho

jidstringobrigatório

JID do grupo (…@g.us).

Corpo (JSON)

actionstringobrigatório

add, remove, promote ou demote.

participantsstring[]obrigatório

Telefones ou JIDs.

error por pessoa segue o WhatsApp: 403 costuma ser privacidade (a pessoa não aceita ser adicionada), 409 já está no grupo.

curl -X POST "https://api.konversa.email:8443/v1/groups/120363025246125486%40g.us/participants" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "add",
  "participants": [
    "5544999998888",
    "5544988887777"
  ]
}'
Resposta200 OK
{
  "data": [
    {
      "jid": "5544999998888@s.whatsapp.net",
      "phone": "5544999998888"
    },
    {
      "jid": "5544988887777@s.whatsapp.net",
      "phone": "5544988887777",
      "error": 403
    }
  ]
}

Alterar grupo

PATCH/v1/groups/{jid}

Nome, descrição, foto e aprovação de entrada. Mande só o que quer mudar.

Parâmetros do caminho

jidstringobrigatório

JID do grupo (…@g.us).

Corpo (JSON)

namestring

Novo nome.

descriptionstring

Nova descrição.

imagestring

URL, data URI base64 ou "remove".

join_approvalboolean

Exige aprovação de um admin para entrar.

curl -X PATCH "https://api.konversa.email:8443/v1/groups/120363025246125486%40g.us" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes VIP 💜",
  "join_approval": true
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Só admins enviam

POST/v1/groups/{jid}/announce

Liga ou desliga o modo em que só admins mandam mensagem no grupo.

Parâmetros do caminho

jidstringobrigatório

JID do grupo (…@g.us).

Corpo (JSON)

announcebooleanobrigatório

true = só admins enviam.

curl -X POST "https://api.konversa.email:8443/v1/groups/120363025246125486%40g.us/announce" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "announce": true
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Ligações

Ligações de voz do WhatsApp com áudio, no mesmo número das mensagens. O áudio vai para o navegador por WebRTC ou é tocado pelo próprio servidor (URA). Cada mudança de estado chega no evento call.

Ligar

POST/v1/calls

Faz uma ligação de voz. Opcionalmente já começa gravando quando a pessoa atender.

Corpo (JSON)

tostringobrigatório

Telefone com DDI (5544999998888), JID de contato (…@s.whatsapp.net) ou de grupo (…@g.us).

recordboolean

Grava a ligação a partir do atendimento.

announceboolean

Avisa as pessoas na ligação de que ela está sendo gravada.

429 indica limite de ligações simultâneas (MAX_CALLS_PER_SESSION, 8 por padrão) ou bloqueio de contato novo.

curl -X POST "https://api.konversa.email:8443/v1/calls" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "5544999998888",
  "record": true,
  "announce": true
}'
Resposta200 OK
{
  "data": {
    "call_id": "A1B2C3D4E5F60718",
    "peer": "5544999998888@s.whatsapp.net"
  }
}

Ligações em andamento

GET/v1/calls

Ligações ativas desta instância.

curl "https://api.konversa.email:8443/v1/calls" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": [
    {
      "call_id": "A1B2C3D4E5F60718",
      "direction": "outbound",
      "peer": "5544999998888@s.whatsapp.net",
      "peer_phone": "5544999998888",
      "state": "active",
      "recording": true,
      "started_at": "2026-10-21T14:32:10Z",
      "duration_ms": 48210
    }
  ]
}

Atender

POST/v1/calls/{id}/accept

Atende uma ligação recebida (estado ringing). O corpo é opcional.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

Corpo (JSON)

recordboolean

Grava desde o atendimento.

announceboolean

Avisa que a ligação está sendo gravada.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/accept" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "record": true
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Recusar

POST/v1/calls/{id}/decline

Recusa uma ligação recebida.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/decline" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Desligar

POST/v1/calls/{id}/end

Encerra a ligação.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/end" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Áudio no navegador

POST/v1/calls/{id}/webrtc

Liga o áudio da ligação a um navegador por WebRTC. Mande a oferta SDP e use a resposta para completar a conexão.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

Corpo (JSON)

sdp_offerstringobrigatório

SDP da RTCPeerConnection (offer.sdp).

O áudio trafega num data channel chamado pcm: PCM 16 kHz, mono, Int16 little-endian, nos dois sentidos.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/webrtc" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sdp_offer": "v=0\r\no=- 4611731400430051336 2 IN IP4 127.0.0.1\r\n…"
}'
Resposta200 OK
{
  "data": {
    "sdp_answer": "v=0\r\no=- 1729520530 1729520530 IN IP4 0.0.0.0\r\n…"
  }
}

Entrar na ligação

POST/v1/calls/{id}/join

Mais um atendente entra no áudio (conferência). key identifica esse atendente para tirá-lo depois.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

Corpo (JSON)

sdp_offerstringobrigatório

SDP do navegador do atendente.

keystringobrigatório

Identificador do atendente (ex.: ID do usuário).

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/join" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sdp_offer": "v=0\r\n…",
  "key": "user_42"
}'
Resposta200 OK
{
  "data": {
    "sdp_answer": "v=0\r\n…"
  }
}

Sair do áudio

POST/v1/calls/{id}/detach

Tira um atendente do áudio sem encerrar a ligação. key vazio tira o atendente principal (para transferir).

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

Corpo (JSON)

keystring

Atendente a remover; vazio = principal.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/detach" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "user_42"
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Gravar

POST/v1/calls/{id}/record

Liga ou desliga a gravação no meio da ligação. Cada trecho gravado gera um evento call_recording.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

Corpo (JSON)

onbooleanobrigatório

true começa, false para.

announceboolean

Avisa que a ligação está sendo gravada.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/record" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "on": true,
  "announce": true
}'
Resposta200 OK
{
  "data": {
    "ok": true,
    "recording": true
  }
}

Tocar áudio (URA)

POST/v1/calls/{id}/play

O servidor toca um áudio na ligação: saudação, menu ou música de espera.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

Corpo (JSON)

urlstringobrigatório

Link https:// de um WAV PCM 16 bits (qualquer taxa, mono ou estéreo).

loopboolean

Repete até stop-audio (música de espera).

422 = o arquivo não é um WAV PCM 16 bits. O áudio fica em cache pela URL.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/play" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://seusite.com/ura/boas-vindas.wav"
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Parar áudio

POST/v1/calls/{id}/stop-audio

Para o áudio que o servidor está tocando.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/stop-audio" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Temporizador

POST/v1/calls/{id}/timer

Agenda o evento call_timer com a tag informada depois de ms milissegundos. Use para montar a URA: “se ninguém atender em 20 s, toca a espera”.

Parâmetros do caminho

idstringobrigatório

call_id da ligação.

Corpo (JSON)

msnumberobrigatório

Espera em milissegundos.

tagstringobrigatório

Até 120 caracteres; volta no evento.

curl -X POST "https://api.konversa.email:8443/v1/calls/A1B2C3D4E5F60718/timer" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "ms": 20000,
  "tag": "sem-atendente"
}'
Resposta200 OK
{
  "data": {
    "ok": true
  }
}

Eventos e webhook

Receba os eventos de dois jeitos: no seu webhook (precisa de URL pública) ou por GET /v1/events, uma conexão que você abre e que funciona até no localhost. Os dois entregam o mesmo envelope.

Eventos em tempo real

GET/v1/events

Abre uma conexão Server-Sent Events e recebe cada evento assim que acontece, sem precisar de URL pública. Ideal para desenvolver no localhost, atrás de firewall ou em servidores sem domínio.

Query

eventsstring

Só estes eventos, separados por vírgula (ex.: message,receipt). Omita para receber todos.

sincenumber

Reenvia os eventos guardados depois deste id. O mesmo que o cabeçalho Last-Event-ID.

Cada bloco traz id, event e data (o mesmo envelope do webhook, em uma linha). Linhas que começam com : são sinal de vida, enviado a cada 25 s: ignore.

Caiu? Reconecte mandando o último id recebido em Last-Event-ID: os eventos que você perdeu são reenviados (guardamos os últimos 100 por instância).

Até 3 conexões ao mesmo tempo por instância; a quarta recebe 429. Quem não lê rápido o bastante é desconectado e recupera o que perdeu ao reconectar.

curl -N "https://api.konversa.email:8443/v1/events" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
retry: 3000
: conectado

id: 1792615139506001
event: message
data: {"instance_id":"inst_8f3a2c","event":"message","timestamp":"2026-10-21T14:32:10Z","data":{"id":"3A5F2B8E1C04D7A96E21","chat":"5544999998888@s.whatsapp.net","type":"text","text":"Oi!","from_me":false}}

: ping

Consultar webhook

GET/v1/webhook

A URL que recebe os eventos desta instância.

curl "https://api.konversa.email:8443/v1/webhook" \
  -H "Authorization: Bearer SEU_TOKEN"
Resposta200 OK
{
  "data": {
    "url": "https://seusite.com/hooks/whatsapp"
  }
}

Trocar webhook

PATCH/v1/webhook

Troca a URL que recebe os eventos, por exemplo quando o endereço do seu túnel muda. "" desliga o webhook.

Corpo (JSON)

urlstringobrigatório

URL pública https:// (ou http://). "" desliga.

Endereços internos (localhost, 127.0.0.1, 192.168.x.x, 10.x.x.x…) são recusados com 400: o servidor não alcança a sua máquina. No localhost, use GET /v1/events ou um túnel.

curl -X PATCH "https://api.konversa.email:8443/v1/webhook" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://abc-123.trycloudflare.com/hooks/whatsapp"
}'
Resposta200 OK
{
  "data": {
    "url": "https://abc-123.trycloudflare.com/hooks/whatsapp"
  }
}
Desenvolvimento

No localhost

Chamar a API do seu computador funciona normalmente: é uma requisição https como outra qualquer. Faça as chamadas pelo seu backend, não pelo navegador (a API não libera CORS, e o token não deve ficar exposto). O que não chega sozinho é o webhook: o servidor não alcança o seu localhost. Escolha um destes caminhos:

1. Eventos em tempo real

recomendado

O seu programa abre a conexão e os eventos descem por ela. Não precisa de URL pública, túnel nem porta aberta.

Terminal
curl -N "https://api.konversa.email:8443/v1/events" \
  -H "Authorization: Bearer SEU_TOKEN"
Exemplos em JavaScript e Python

2. Túnel para o webhook

Gera uma URL pública que aponta para a sua máquina. Cadastre-a como webhook e troque de novo sempre que o túnel mudar de endereço.

Terminal
# porta do seu app
npx cloudflared tunnel --url http://localhost:3000

# use a URL que aparecer
curl -X PATCH "https://api.konversa.email:8443/v1/webhook" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://abc-123.trycloudflare.com/hooks/whatsapp" }'
Webhook

Formato e assinatura

Cada evento chega como POST no webhook_url da instância, com o mesmo envelope. Confira sempre a assinatura antes de confiar no conteúdo.

Cabeçalhos

X-Konversa-Signaturestring

sha256= + HMAC-SHA256 do corpo cru, em hex, usando o webhook_secret.

X-Konversa-Eventstring

Nome do evento (o mesmo de event): dá para rotear sem ler o corpo.

Entrega e novas tentativas

Responda com qualquer 2xx em até 15 segundos. Se falhar, tentamos de novo após 2 s, 10 s e 30 s, e então o evento é descartado.

Responda rápido e processe em segundo plano. O mesmo evento pode chegar duas vezes: use o id para não duplicar.

Envelope
{
  "instance_id": "inst_8f3a2c",
  "event": "message",
  "timestamp": "2026-10-21T14:32:10.512Z",
  "data": {
    "…": "…"
  }
}
import crypto from "node:crypto";
import express from "express";

const app = express();

// Use o corpo CRU: a assinatura é calculada sobre os bytes recebidos.
app.post("/hooks/whatsapp", express.raw({ type: "application/json" }), (req, res) => {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", process.env.KONVERSA_WEBHOOK_SECRET).update(req.body).digest("hex");
  const got = req.get("X-Konversa-Signature") ?? "";
  const ok = got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);

  const { event, data } = JSON.parse(req.body.toString());
  res.sendStatus(200); // responda rápido; processe em fila
  if (event === "message" && !data.from_me) console.log(data.push_name, data.text);
});

Eventos

data · message
{
  "id": "3A5F2B8E1C04D7A96E21",
  "chat": "5544999998888@s.whatsapp.net",
  "chat_type": "user",
  "chat_phone": "5544999998888",
  "sender": "5544999998888@s.whatsapp.net",
  "sender_phone": "5544999998888",
  "push_name": "Maria Souza",
  "from_me": false,
  "timestamp": "2026-10-21T14:32:10Z",
  "type": "image",
  "text": "Olha o comprovante",
  "media": {
    "mime_type": "image/jpeg",
    "size": 184213,
    "width": 1080,
    "height": 1920,
    "url": "https://api.konversa.email:8443/v1/media/3A5F2B8E1C04D7A96E21?instance=inst_8f3a2c&exp=1729606930&sig=…"
  },
  "quoted_id": "3EB0C431C26A1916E07A"
}