API v2 Contatti e lead
Elenca contatti e lead, crea o aggiorna un contatto tramite ID esterno e importa contatti in blocco per un agente.
Contact payloads expose customAttributes; write requests accept customAttributes.plan and other JSON keys such as customAttributes.seats.
I contatti associano i tuoi ID utente finale stabili a nomi, indirizzi e-mail e numeri di telefono. I lead sono invii di sola lettura raccolti da un agente. Ogni endpoint di questa pagina richiede Authorization: Bearer YOUR_API_KEY e l'accesso a {agentId}.
Per le dichiarazioni di identità firmate nella chat incorporata, consulta Verifica dell'identità. Consulta il catalogo degli errori per gli errori di autenticazione e validazione comuni.
Oggetto contatto
| Campo | Tipo | Note |
|---|---|---|
id | stringa | UUID del contatto. |
externalId | stringa | Il tuo ID utente finale stabile. |
name | stringa o null | Nome del contatto. |
email | stringa o null | Indirizzo e-mail del contatto. |
phone | stringa o null | Numero di telefono del contatto. |
createdAt | intero o null | Timestamp Unix in secondi. |
updatedAt | intero o null | Timestamp Unix in secondi. |
lastSeenAt | intero o null | Timestamp Unix in secondi. |
Elenca i contatti
Percorso: /api/v2/agents/{agentId}/contacts
GET /api/v2/agents/{agentId}/contacts
Autenticazione: Chiave API Bearer con accesso a {agentId}.
| Query | Obbligatorio | Vincoli |
|---|---|---|
limit | No | Intero da 1 a 100; il valore predefinito è 20. |
cursor | No | Cursore opaco restituito dalla pagina precedente. Riproponilo invariato. |
search | No | Ricerca per sottostringa senza distinzione tra maiuscole e minuscole (ILIKE) su ID esterno, e-mail, nome e telefono, con spazi iniziali/finali rimossi. I segni di percentuale (%) vengono rimossi, ma il trattino basso (_) non viene neutralizzato e funge da carattere jolly per un singolo carattere — ad es. acct_1 corrisponde anche a acctX1. Un risultato vuoto dopo la rimozione degli spazi viene ignorato. |
curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts?search=alice&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY'
Successo: 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
}
}
Limiti o cursori non validi restituiscono 400 VALIDATION_INVALID_BODY.
Oggetto lead
| Campo | Tipo | Note |
|---|---|---|
id | stringa | UUID del lead. |
name | stringa o null | Nome inviato. |
email | stringa o null | Indirizzo e-mail inviato. |
phone | stringa o null | Numero di telefono inviato. |
conversationId | stringa o null | ID di riferimento pubblico della conversazione, quando il lead è collegato a una conversazione. |
createdAt | intero | Timestamp Unix in secondi. |
Elenca i lead
Percorso: /api/v2/agents/{agentId}/leads
GET /api/v2/agents/{agentId}/leads
Autenticazione: Chiave API Bearer con accesso a {agentId}.
| Query | Obbligatorio | Vincoli |
|---|---|---|
limit | No | Intero da 1 a 100; il valore predefinito è 20. |
cursor | No | Cursore opaco restituito dalla pagina precedente. Riproponilo invariato. |
createdAfter | No | Data e ora ISO 8601 con Z o un offset UTC. Il limite inferiore è incluso. |
createdBefore | No | Data e ora ISO 8601 con Z o un offset UTC. Il limite superiore è incluso. |
Quando sono presenti entrambi i filtri di data, createdAfter deve essere minore o uguale a createdBefore se confrontati come istanti. Limiti uguali sono validi.
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'
Successo: 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
}
}
I lead sono ordinati per data di invio, dal più recente al più vecchio. Limiti, cursori, date/ore o intervalli di date invertiti non validi restituiscono 400 VALIDATION_INVALID_BODY.
Crea o aggiorna un contatto
POST /api/v2/agents/{agentId}/contacts
Autenticazione: Chiave API Bearer con accesso a {agentId}.
Questo endpoint crea o aggiorna in base alla coppia {agentId, externalId}. Se esiste già un contatto corrispondente, vengono aggiornati solo i campi del profilo presenti nella richiesta. Un campo omesso conserva il valore memorizzato; un null esplicito o una stringa vuota lo cancella.
| Campo del corpo | Obbligatorio | Tipo e vincoli |
|---|---|---|
externalId | Sì | Stringa, con spazi iniziali/finali rimossi, da 1 a 255 caratteri. |
name | No | Stringa di massimo 255 caratteri (spazi rimossi), oppure null. |
email | No | Indirizzo e-mail valido di massimo 320 caratteri (spazi rimossi), una stringa vuota o null. |
phone | No | Stringa di massimo 50 caratteri (spazi rimossi), una stringa vuota 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}}'
Successo: 201 Created sia per gli inserimenti sia per gli aggiornamenti in caso di conflitto. L'oggetto contatto viene restituito diretto.
{
"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
}
I corpi non validi restituiscono 400 VALIDATION_INVALID_BODY con i dettagli di validazione.
Importa contatti
Percorso: /api/v2/agents/{agentId}/contacts/import
POST /api/v2/agents/{agentId}/contacts/import
Autenticazione: Chiave API Bearer con accesso a {agentId}.
La richiesta usa nomi di campo in snake_case. rows deve contenere da 1 a 1.000 voci.
| Campo della riga | Obbligatorio | Tipo e vincoli |
|---|---|---|
external_id | Sì | Stringa, con spazi iniziali/finali rimossi, da 1 a 255 caratteri. |
name | No | Stringa di massimo 255 caratteri (spazi rimossi), oppure null. |
email | No | Indirizzo e-mail valido di massimo 320 caratteri (spazi rimossi), una stringa vuota o null. |
phone | No | Stringa di massimo 50 caratteri (spazi rimossi), oppure null; è accettata anche una stringa vuota, memorizzata come null. |
Le righe vengono deduplicate in base a external_id all'interno della richiesta; vince l'ultima occorrenza. A differenza dell'upsert parziale del singolo contatto, l'importazione costruisce ogni campo del profilo per ciascuna riga mantenuta, quindi un valore di profilo omesso, null o vuoto viene memorizzato come null in caso di conflitto.
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}]}'
Successo: 200 OK
{
"processed": 2,
"skipped": 0
}
processed è il numero di ID esterni univoci creati o aggiornati. skipped è il numero di righe duplicate rimosse dal batch inviato. I corpi non validi, inclusi i batch vuoti e quelli con più di 1.000 righe, restituiscono 400 VALIDATION_INVALID_BODY.