Contactos y leads de la API v2
Lista contactos y leads, actualiza un contacto por ID externo e importa contactos en bloque para un agente.
Contact payloads expose customAttributes; write requests accept customAttributes.plan and other JSON keys such as customAttributes.seats.
Los contactos asocian tus propios ID estables de usuario final con nombres, direcciones de correo electrónico y números de teléfono. Los leads son envíos de solo lectura capturados por un agente. Todos los endpoints de esta página requieren Authorization: Bearer YOUR_API_KEY y acceso a {agentId}.
Para conocer las declaraciones de identidad firmadas en el chat integrado, consulta Verificación de identidad. Consulta el catálogo de errores para conocer los errores compartidos de autenticación y validación.
Objeto de contacto
| Campo | Tipo | Notas |
|---|---|---|
id | string | UUID del contacto. |
externalId | string | Tu ID estable de usuario final. |
name | string o null | Nombre del contacto. |
email | string o null | Dirección de correo electrónico del contacto. |
phone | string o null | Número de teléfono del contacto. |
createdAt | integer o null | Marca de tiempo Unix en segundos. |
updatedAt | integer o null | Marca de tiempo Unix en segundos. |
lastSeenAt | integer o null | Marca de tiempo Unix en segundos. |
Listar contactos
Ruta: /api/v2/agents/{agentId}/contacts
GET /api/v2/agents/{agentId}/contacts
Autenticación: Clave de API bearer con acceso a {agentId}.
| Query | Requerido | Restricciones |
|---|---|---|
limit | No | Número entero de 1 a 100; el valor predeterminado es 20. |
cursor | No | Cursor opaco devuelto por la página anterior. Reenvíalo sin modificarlo. |
search | No | Búsqueda de subcadena recortada, sin distinción entre mayúsculas y minúsculas (ILIKE), en el ID externo, el correo electrónico, el nombre y el teléfono. Los signos de porcentaje (%) se eliminan, pero el guion bajo (_) no se escapa y actúa como comodín de un solo carácter; por ejemplo, acct_1 también coincide con acctX1. Un resultado vacío después de recortar se ignora. |
curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts?search=alice&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY'
Éxito: 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
}
}
Los límites o cursores inválidos devuelven 400 VALIDATION_INVALID_BODY.
Objeto de lead
| Campo | Tipo | Notas |
|---|---|---|
id | string | UUID del lead. |
name | string o null | Nombre enviado. |
email | string o null | Dirección de correo electrónico enviada. |
phone | string o null | Número de teléfono enviado. |
conversationId | string o null | ID de referencia pública de la conversación cuando el lead está vinculado a una conversación. |
createdAt | integer | Marca de tiempo Unix en segundos. |
Listar leads
Ruta: /api/v2/agents/{agentId}/leads
GET /api/v2/agents/{agentId}/leads
Autenticación: Clave de API bearer con acceso a {agentId}.
| Query | Requerido | Restricciones |
|---|---|---|
limit | No | Número entero de 1 a 100; el valor predeterminado es 20. |
cursor | No | Cursor opaco devuelto por la página anterior. Reenvíalo sin modificarlo. |
createdAfter | No | Fecha y hora ISO 8601 con Z o un desfase UTC. El límite inferior es inclusivo. |
createdBefore | No | Fecha y hora ISO 8601 con Z o un desfase UTC. El límite superior es inclusivo. |
Cuando ambos filtros de fecha están presentes, createdAfter debe ser menor o igual que createdBefore al compararse como instantes. Los límites iguales son 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'
Éxito: 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
}
}
Los leads se ordenan por hora de envío, de más reciente a más antiguo. Los límites, cursores, fechas u orden de límites invertido inválidos devuelven 400 VALIDATION_INVALID_BODY.
Crear o actualizar un contacto
POST /api/v2/agents/{agentId}/contacts
Autenticación: Clave de API bearer con acceso a {agentId}.
Este endpoint actualiza o inserta según el par {agentId, externalId}. Cuando existe un contacto coincidente, solo se actualizan los campos de perfil presentes en la solicitud. Un campo omitido conserva su valor almacenado; un null explícito o un string vacío lo borran.
| Campo del cuerpo | Requerido | Tipo y restricciones |
|---|---|---|
externalId | Sí | String, recortado, de 1 a 255 caracteres. |
name | No | String recortado a un máximo de 255 caracteres, o null. |
email | No | Dirección de correo electrónico válida recortada a un máximo de 320 caracteres, un string vacío o null. |
phone | No | String recortado a un máximo de 50 caracteres, un string vacío o 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}}'
Éxito: 201 Created tanto para inserciones como para actualizaciones por conflicto. El objeto de contacto se devuelve simple.
{
"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
}
Los cuerpos inválidos devuelven 400 VALIDATION_INVALID_BODY con detalles de validación.
Importar contactos
Ruta: /api/v2/agents/{agentId}/contacts/import
POST /api/v2/agents/{agentId}/contacts/import
Autenticación: Clave de API bearer con acceso a {agentId}.
La solicitud usa nombres de campo en snake_case. rows debe contener de 1 a 1.000 entradas.
| Campo de fila | Requerido | Tipo y restricciones |
|---|---|---|
external_id | Sí | String, recortado, de 1 a 255 caracteres. |
name | No | String recortado a un máximo de 255 caracteres, o null. |
email | No | Dirección de correo electrónico válida recortada a un máximo de 320 caracteres, un string vacío o null. |
phone | No | String recortado a un máximo de 50 caracteres, o null; también se acepta un string vacío, que se almacena como null. |
Las filas se deduplican por external_id dentro de la solicitud; gana la última repetición. A diferencia de la actualización parcial de un solo contacto, la importación construye todos los campos de perfil para cada fila retenida, de modo que un valor de perfil omitido, null o vacío se almacena como null en caso de conflicto.
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}]}'
Éxito: 200 OK
{
"processed": 2,
"skipped": 0
}
processed es la cantidad de ID externos únicos actualizados o insertados. skipped es la cantidad de filas duplicadas eliminadas del lote enviado. Los cuerpos inválidos, incluidos los lotes vacíos y los lotes de más de 1.000 filas, devuelven 400 VALIDATION_INVALID_BODY.