Introdução

A API v3 é a mesma sobre a qual o painel do Pingo roda. Tudo o que você faz no produto, você faz aqui.

URL base

https://api.pingonotify.com

O que mudou da v2

A v2 era um conjunto de endpoints para os números de WhatsApp de um usuário. A v3 é organizada em torno de um workspace — um inquilino compartilhado que é dono das conexões, contatos, conversas e cobrança, e ao qual várias pessoas podem pertencer com papéis diferentes.

Essa reorganização traz três coisas que a v2 não tem:

• Uma caixa de entrada compartilhada. Conversas, contatos, atribuição, SLAs, bots, relatórios — o helpdesk inteiro.
• Campanhas. Uma mensagem para muitos destinatários, ritmada e medida.
• Equipes. Membros, papéis e acesso por caixa de entrada.

Os endpoints de mensagem da v2 têm equivalentes diretos na v3, com uma mudança consistente: o destinatário nunca fica na URL. Na v2 você enviava para /v2/connections/{id}/chats/{remoteJid}/messages; na v3 o número viaja no corpo como to, de modo que um número de telefone nunca acaba em uma linha de log ou no cache de um proxy.

Sua primeira requisição

Liste os workspaces que o seu token alcança:

curl https://api.pingonotify.com/v3/accounts \
  -H "apikey: sk_live_..."

[
  {
    "id": "0195f3a0-1234-7890-abcd-ef0123456789",
    "name": "Acme",
    "isPersonal": false,
    "roles": ["OWNER"],
    "helpdeskEnabled": true
  }
]

Depois envie uma mensagem por uma das suas conexões:

curl -X POST https://api.pingonotify.com/v3/connections/{connectionId}/chats/messages \
  -H "apikey: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999998888",
    "text": "Olá, aqui é o Pingo"
  }'

Como as peças se encaixam

Uma conexão é um número de WhatsApp. Ela é oficial (a Cloud API da Meta, usando as suas próprias credenciais da Meta) ou não oficial (uma conta real do WhatsApp pareada por QR code ou sync do navegador). Tudo que envia ou recebe mensagem roda, no fim, sobre uma conexão.

Você pode usar uma conexão de três formas, e elas se somam:

1. Diretamente. Envie e leia mensagens na própria conexão — o mais parecido com a v2, e a escolha certa para notificações e mensagens transacionais.
2. Por uma campanha. Uma mensagem, muitos destinatários, ritmada para que um número não oficial não seja sinalizado, e medida contra o seu plano.
3. Pelo helpdesk. Vincule a conexão a uma caixa de entrada, e as mensagens recebidas viram conversas que a sua equipe pode atribuir, etiquetar, adiar e responder — com bots, SLAs e relatórios por cima.

O helpdesk ainda tem um quarto tipo de caixa que não é um número de WhatsApp: o canal de API, uma caixa programável na qual o seu próprio aplicativo injeta mensagens e da qual recebe as respostas por webhook. Ele permite colocar qualquer canal que você queira — um widget no site, um chat dentro do app, outro mensageiro — atrás da mesma caixa compartilhada.

A única coisa que você precisa saber sobre o WhatsApp

O WhatsApp não deixa uma empresa mandar mensagem para alguém quando quiser. Em uma conexão oficial, passadas 24 horas desde a última mensagem do contato, você não pode mais enviar texto livre — só pode enviar um template que a Meta aprovou previamente.

A API é explícita quanto a isso. Enviar texto livre com a janela fechada retorna 422:

{
  "statusCode": 422,
  "message": "Outbound window expired — channel requires a pre-approved template",
  "error": "Unprocessable Entity"
}

Envie um template aprovado no lugar, e a janela reabre assim que o contato responder. Gerencie seus templates com GET /v3/connections/{id}/templates.

Conexões não oficiais não têm essa janela.

Por onde seguir