Pareamento
Ligue o contato do WhatsApp ou do Instagram à conta dele no seu sistema: você gera um código, a pessoa manda o código para o chatbot e confirma. Depois disso, as ações recebem o id dela no seu sistema.
pairingPacoteIntegrações (R$ 49 por mês, por conta). Sem ele, a API responde 403 plan_not_allowed.| Rota | O que faz |
|---|---|
POST /v1/pairings | Gera o código (6 caracteres, uso único, 10 minutos) e o link que a pessoa abre. |
GET /v1/contacts/{contact}/links | Os vínculos ativos do contato. |
DELETE /v1/contacts/{contact}/links/{id} | Desfaz um vínculo. |
O caminho completo, com o que a pessoa vê no chat e o que as ações recebem, está em Identificar usuários.
POST/v1/pairings
O pareamento só termina quando a pessoa abre o link no celular (ele abre o chat do chatbot com “Conectar <código>” escrito) e manda a mensagem; se o contato já estava ligado a outra conta, ele confirma antes. Sai o webhook contact.linked. Nas conversas seguintes, o chatbot pergunta “Estou falando com <name>?” antes de usar a conta (veja Identificar usuários).
curl -X POST "https://boavoz.com/api/v1/pairings" \
-H "Authorization: Bearer $BOAVOZ_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
-d '{
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"channel": "whatsapp",
"external_id": "usuario_8812",
"display": {
"name": "Teste Postman"
}
}'{
"code": "K7Q2M9",
"link": "https://wa.me/5511999990000?text=Conectar%20K7Q2M9",
"expires_at": "2026-10-19T15:40:00.000Z"
}| Campo | Regra | Erro |
|---|---|---|
bot_id | Obrigatório; o chatbot precisa ter o canal conectado. | 403 forbidden_scope; 422 channel_not_connected |
channel | whatsapp ou instagram. | 400 channel |
external_id | Obrigatório: o id da pessoa no seu sistema (até 128 caracteres). Volta para as ações e na API como ext:. | 400 external_id |
context | Opcional: um objeto seu (até 2 KB), entregue às ações junto do external_id. A IA não vê. | 400 context |
display | Opcional: {name, workspace_name} (até 80 caracteres cada), o que a IA pode usar na conversa. | 400 display… |
expected_phone | Opcional, só no WhatsApp: o número que você espera (com DDD). Outro número tentando o código não pareia. | 400 expected_phone |
GET/v1/contacts/{contact}/links
source diz de onde veio o vínculo: pairing (pelo código) ou routine (o número lembrado pelo roteiro, com a licença da pessoa). Com ext: sem vínculo ativo, a lista vem vazia.
curl "https://boavoz.com/api/v1/contacts/ext:usuario_8812/links" \
-H "Authorization: Bearer $BOAVOZ_API_KEY"{
"data": [
{
"id": "lnk_4d5e6f7a-8b9c-4d0e-a1f2-3b4c5d6e7f8a",
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"contact_id": "ctc_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"channel": "whatsapp",
"source": "pairing",
"external_id": "usuario_8812",
"context": null,
"display": {
"name": "Teste Postman"
},
"phone_masked": "+55 11 9•••• 0000",
"linked_at": "2026-10-19T15:31:40.000Z"
}
]
}DELETE/v1/contacts/{contact}/links/{id}
Responde 204. Sai o webhook contact.unlinked. Id que não é lnk_…: 400 id.
curl -X DELETE "https://boavoz.com/api/v1/contacts/ext:usuario_8812/links/lnk_4d5e6f7a-8b9c-4d0e-a1f2-3b4c5d6e7f8a" \
-H "Authorization: Bearer $BOAVOZ_API_KEY"(sem corpo)