API v2 Contatos e Leads
Liste contatos e leads, crie ou atualize um contato pelo ID externo, e importe contatos em massa para um agente.
Contact payloads expose customAttributes; write requests accept customAttributes.plan and other JSON keys such as customAttributes.seats.
Contatos associam seus próprios IDs estáveis de usuário final a nomes, endereços de e-mail e números de telefone. Leads são submissões somente leitura capturadas por um agente. Todo endpoint nesta página exige Authorization: Bearer YOUR_API_KEY e acesso a {agentId}.
Para declarações de identidade assinadas no chat incorporado, veja Verificação de Identidade. Veja o catálogo de erros para erros compartilhados de autenticação e validação.
Objeto Contact
| Campo | Tipo | Notas |
|---|---|---|
id | string | UUID do contato. |
externalId | string | Seu ID estável de usuário final. |
name | string ou null | Nome do contato. |
email | string ou null | Endereço de e-mail do contato. |
phone | string ou null | Número de telefone do contato. |
createdAt | integer ou null | Timestamp Unix em segundos. |
updatedAt | integer ou null | Timestamp Unix em segundos. |
lastSeenAt | integer ou null | Timestamp Unix em segundos. |
Listar Contatos
Caminho: /api/v2/agents/{agentId}/contacts
GET /api/v2/agents/{agentId}/contacts
Autenticação: Chave de API Bearer com acesso a {agentId}.
| Query | Obrigatório | Restrições |
|---|---|---|
limit | Não | Inteiro de 1 a 100; o padrão é 20. |
cursor | Não | Cursor opaco retornado pela página anterior. Reenvie sem alterações. |
search | Não | Busca de substring com espaços removidos e sem diferenciação de maiúsculas/minúsculas (ILIKE) em ID externo, e-mail, nome e telefone. Sinais de porcentagem (%) são removidos, mas o sublinhado (_) não é escapado e atua como um curinga de caractere único — por exemplo, acct_1 também corresponde a acctX1. Um resultado vazio após a remoção dos espaços é ignorado. |
curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts?search=alice&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY'
Sucesso: 200 OK
{
"data": [
{
"id": "f9878f31-c2b3-469f-a82e-26e996e67721",
"externalId": "customer_123",
"name": "Alice Example",
"email": "[email protected]",
"phone": "+1 555 0100",
"customAttributes": { "plan": "pro", "seats": 4 },
"createdAt": 1784332800,
"updatedAt": 1784332800,
"lastSeenAt": null
}
],
"pagination": {
"cursor": null,
"hasMore": false,
"total": 1
}
}
Limites ou cursores inválidos retornam 400 VALIDATION_INVALID_BODY.
Objeto Lead
| Campo | Tipo | Notas |
|---|---|---|
id | string | UUID do lead. |
name | string ou null | Nome enviado. |
email | string ou null | Endereço de e-mail enviado. |
phone | string ou null | Número de telefone enviado. |
conversationId | string ou null | ID de referência pública da conversa quando o lead está vinculado a uma conversa. |
createdAt | integer | Timestamp Unix em segundos. |
Listar Leads
Caminho: /api/v2/agents/{agentId}/leads
GET /api/v2/agents/{agentId}/leads
Autenticação: Chave de API Bearer com acesso a {agentId}.
| Query | Obrigatório | Restrições |
|---|---|---|
limit | Não | Inteiro de 1 a 100; o padrão é 20. |
cursor | Não | Cursor opaco retornado pela página anterior. Reenvie sem alterações. |
createdAfter | Não | Data e hora no formato ISO 8601 com Z ou um deslocamento UTC. O limite inferior é inclusivo. |
createdBefore | Não | Data e hora no formato ISO 8601 com Z ou um deslocamento UTC. O limite superior é inclusivo. |
Quando ambos os filtros de data estão presentes, createdAfter deve ser menor ou igual a createdBefore quando comparados como instantes. Limites iguais são válidos.
curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/leads?createdAfter=2026-07-18T08:00:00Z&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY'
Sucesso: 200 OK
{
"data": [
{
"id": "ad47f673-6bfb-43a0-a296-d79c84870a32",
"name": "Alice Example",
"email": "[email protected]",
"phone": "+1 555 0100",
"conversationId": "a1b2c3d4e5f6g7h8",
"createdAt": 1784361600
}
],
"pagination": {
"cursor": null,
"hasMore": false,
"total": 1
}
}
Os leads são ordenados por horário de envio, do mais recente ao mais antigo. Limites, cursores, datas e horas inválidos, ou limites de data invertidos, retornam 400 VALIDATION_INVALID_BODY.
Criar ou Atualizar Um Contato
POST /api/v2/agents/{agentId}/contacts
Autenticação: Chave de API Bearer com acesso a {agentId}.
Este endpoint cria ou atualiza com base no par {agentId, externalId}. Quando um contato correspondente já existe, apenas os campos de perfil presentes na requisição são atualizados. Um campo omitido preserva seu valor armazenado; um null explícito ou uma string vazia o limpa.
| Campo do corpo | Obrigatório | Tipo e restrições |
|---|---|---|
externalId | Sim | String, com espaços removidos, de 1 a 255 caracteres. |
name | Não | String reduzida a no máximo 255 caracteres, ou null. |
email | Não | Endereço de e-mail válido reduzido a no máximo 320 caracteres, uma string vazia, ou null. |
phone | Não | String reduzida a no máximo 50 caracteres, uma string vazia, ou null. |
curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"externalId":"customer_123","name":"Alice Example","email":"[email protected]","customAttributes":{"plan":"pro","seats":4}}'
Sucesso: 201 Created tanto para inserções quanto para atualizações por conflito. O objeto de contato é retornado diretamente.
{
"id": "f9878f31-c2b3-469f-a82e-26e996e67721",
"externalId": "customer_123",
"name": "Alice Example",
"email": "[email protected]",
"phone": null,
"customAttributes": { "plan": "pro", "seats": 4 },
"createdAt": 1784332800,
"updatedAt": 1784332800,
"lastSeenAt": null
}
Corpos inválidos retornam 400 VALIDATION_INVALID_BODY com detalhes da validação.
Importar Contatos
Caminho: /api/v2/agents/{agentId}/contacts/import
POST /api/v2/agents/{agentId}/contacts/import
Autenticação: Chave de API Bearer com acesso a {agentId}.
A requisição usa nomes de campo em snake_case. rows deve conter de 1 a 1.000 entradas.
| Campo da linha | Obrigatório | Tipo e restrições |
|---|---|---|
external_id | Sim | String, com espaços removidos, de 1 a 255 caracteres. |
name | Não | String reduzida a no máximo 255 caracteres, ou null. |
email | Não | Endereço de e-mail válido reduzido a no máximo 320 caracteres, uma string vazia, ou null. |
phone | Não | String reduzida a no máximo 50 caracteres, ou null; uma string vazia também é aceita e armazenada como null. |
As linhas são deduplicadas por external_id dentro da requisição; a última ocorrência prevalece. Diferentemente da criação/atualização parcial de contato único, a importação constrói todos os campos de perfil para cada linha retida, então um valor de perfil omitido, null, ou vazio é armazenado como null em caso de conflito.
curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts/import' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"rows":[{"external_id":"customer_123","name":"Alice Example","email":"[email protected]","phone":"+1 555 0100","customAttributes":{"plan":"pro"}},{"external_id":"customer_456","name":"Bob Example","email":"[email protected]","phone":null}]}'
Sucesso: 200 OK
{
"processed": 2,
"skipped": 0
}
processed é o número de IDs externos únicos criados ou atualizados. skipped é o número de linhas duplicadas removidas do lote enviado. Corpos inválidos, incluindo lotes vazios e lotes com mais de 1.000 linhas, retornam 400 VALIDATION_INVALID_BODY.