La funzionalità Add Inbound Message ti permette di pubblicare messaggi in entrata nelle Conversazioni fornendo un Contact ID, senza dover prima recuperare un Conversation ID. Questo riduce il numero di chiamate, semplifica la logica e garantisce che i messaggi appaiano nel thread CRM corretto con il minimo overhead. Usa questa guida per comprendere i vantaggi, la configurazione, la struttura del payload, il comportamento di threading e le best practice.

IMPORTANTE: Puoi trovare la documentazione completa delle REST API per la piattaforma HITLEAD CRM qui. HITLEAD API Documentation - Send a new message.

INDICE

Cos'è Add Inbound Message (basato sul Contatto)

Add Inbound Message accetta un Contact ID e pubblica un nuovo messaggio in entrata nella conversazione appropriata — aggiungendolo a un thread esistente oppure creandone uno nuovo. Questo rende le integrazioni più veloci e affidabili quando si acquisiscono messaggi da provider, webhook o importazioni in cui il contatto è già noto.

  • Fornisci il Contact ID + canale + contenuto; il sistema gestisce l'associazione al thread.
  • Se esiste una conversazione corrispondente, il messaggio viene aggiunto; altrimenti ne viene creata una nuova.
  • Funziona sui canali più comuni (es. SMS/MMS, Email, WhatsApp, Messenger, Instagram, Web Chat).

Schermata 1 — Conversations API - Aggiungere un Messaggio in Entrata (con Contact ID)

Vantaggi principali di Add Inbound Message

Questi vantaggi si traducono direttamente in meno round-trip di rete, flussi di sviluppo più chiari e una migliore esperienza degli agenti nel CRM.

  • Meno chiamate API: evita la ricerca/creazione della conversazione nei flussi inbound più comuni
  • Controllo del flusso più semplice: riduce i rami condizionali per "conversazione esiste vs non esiste"
  • UX CRM più pulita: i messaggi atterrano automaticamente nel thread giusto
  • Integrazioni più resilienti: meno chiamate significano meno punti di fallimento transitori
  • Retrocompatibile: i pattern esistenti "tramite Conversation ID" continuano a funzionare

Panoramica Endpoint e Payload (concettuale)

Le strutture seguenti illustrano come costruire le richieste e consumare le risposte. I nomi dei campi sono indicativi; allinea la tua implementazione alla documentazione developer più aggiornata nel tuo ambiente.

HTTP

POST /conversations/inbound-messages
Authorization: Bearer <token>
Content-Type: application/json

Request (rappresentativa)

{
  "contactId": "CONTACT_ID",
  "channel": "sms | whatsapp | email | messenger | instagram | webchat",
  "endpoint": {
    "phone": "+15551234567",
    "email": "user@example.com"
  },
  "content": {
    "text": "Hello from our provider",
    "attachments": [
      {
        "type": "image|file|video",
        "url": "https://example.com/file.jpg",
        "filename": "file.jpg",
        "sizeBytes": 123456
      }
    ]
  },
  "metadata": {
    "providerMessageId": "ext-abc-123",
    "externalThreadKey": "optional-correlation",
    "timestamp": "2026-02-04T10:15:30Z"
  },
  "idempotencyKey": "fd2d5f6f-5a9f-4b0a-8d68-0d5f6a1c9e5a"
}

Response (rappresentativa)

{
  "messageId": "MSG_123",
  "conversationId": "CONV_987",
  "contactId": "CONTACT_ID",
  "channel": "sms",
  "direction": "inbound",
  "createdAt": "2026-02-04T10:15:31Z"
}

Regole di Threading e Associazione

Le regole di threading determinano se il sistema aggiunge il messaggio a una conversazione esistente o ne crea una nuova. Comprendere queste regole previene thread duplicati o frammentati.

  • Thread esistente (stesso canale): Se il contatto ha una conversazione aperta sullo stesso canale, il messaggio viene aggiunto a quel thread.
  • Nessun thread adatto: Il sistema crea una nuova conversazione e restituisce conversationId nella risposta.
  • Più endpoint per contatto: Quando un contatto ha più indirizzi per lo stesso canale (es. due numeri di telefono o email), includi l'endpoint hint (es. endpoint.phone o endpoint.email) per disambiguare.
  • Contesto multi-location: Assicurati che il contesto di autenticazione o il payload sia indirizzato alla location/workspace corretta se il contatto esiste in più location.
  • Thread archiviati/chiusi: Se esistono solo thread chiusi/archiviati, viene creata una nuova conversazione.

Configurazione e Requisiti

Preparare in anticipo credenziali, scope e contesto dell'ambiente migliora l'affidabilità e riduce i tempi di integrazione.

  • Accesso e scope: Verifica l'accesso API e gli scope Conversations/Contacts richiesti per il tuo ruolo.
  • Autenticazione: Usa OAuth o API key secondo gli standard del tuo ambiente.
  • Risoluzione del contatto: Disponi di un metodo affidabile per ottenere/validare i Contact ID a monte (es. tramite corrispondenza telefono/email).
  • Contesto location: Le chiamate devono essere risolte nella location corretta che possiede i dati del contatto e della conversazione.

Considerazioni sui Canali e Allegati

Ogni canale applica regole specifiche. Valida i payload per evitare errori di consegna o upload rifiutati.

  • SMS/MMS: Rispetta i limiti di caratteri e di dimensione/tipo dei media; preferisci URL media raggiungibili dal sistema.
  • WhatsApp: Rispetta i vincoli template/free-form; assicurati che i tipi di media soddisfino le specifiche WhatsApp.
  • Email: Fornisci i tipi MIME corretti; supporto per body text/HTML e allegati.
  • Messenger/Instagram: Possono applicarsi limiti di piattaforma API e rate cap; valida le dimensioni dei media.
  • Web Chat: Il supporto ai contenuti rich dipende dalle capacità del Chat Widget; ricadi sul testo se necessario.

Idempotenza, Retry e Rate Limit

I problemi di rete e i timeout dei provider sono normali. L'idempotenza e una logica di retry disciplinata prevengono i messaggi duplicati e migliorano la fiducia degli utenti.

  • Idempotenza: Includi sempre un idempotencyKey. I retry con la stessa chiave non devono creare duplicati.
  • Politica di retry: Esegui il retry su 5xx/timeout con backoff esponenziale. Rispetta le risposte 429 e l'header Retry-After quando presente.
  • Osservabilità: Registra il tuo request ID e il providerMessageId per correlare con i sistemi downstream.

Gestione degli Errori e Risposte Comuni

Standardizzare la gestione degli errori riduce i tempi di indagine ed evita incongruenze visibili agli utenti.

  • 400 Bad Request — contactId non valido, canale mancante, contenuto malformato, tipo/dimensione allegato non supportato
  • 401/403 — autenticazione fallita o scope/ruolo insufficiente per la location
  • 404 Not Found — contactId non trovato o non visibile nel tuo contesto location
  • 409 Conflict — collisione della chiave di idempotenza o invio duplicato rilevato
  • 413 Payload Too Large — gli allegati superano i limiti di dimensione
  • 429 Too Many Requests — rate limit superato; applica backoff e riprova
  • 5xx — errore transitorio del provider/sistema; riprova con lo stesso idempotencyKey

Test e Verifica

Un piano di test ripetibile garantisce che i messaggi vengano inseriti nel thread corretto e appaiano nel CRM come atteso prima del rilascio in produzione.

  • Percorso standard: Pubblica un messaggio inbound con un contactId noto e verifica che appaia nella conversazione corretta.
  • Caso senza thread: Pubblica per un contatto senza conversazione aperta e verifica che venga restituito un nuovo conversationId.
  • Ambiguità di endpoint: Testa un contatto con più numeri/email; includi gli endpoint hint e verifica il threading corretto.
  • Allegati: Valida i media consentiti e verifica il rendering nella timeline del CRM.
  • Resilienza: Simula i timeout e assicurati che i retry idempotenti non creino duplicati.

Domande Frequenti

D: Posso ancora pubblicare messaggi inbound usando un Conversation ID?

Sì. I flussi esistenti rimangono supportati. Il metodo inbound basato sul contatto è un'aggiunta opzionale.

D: Cosa succede se ometto il canale?

La richiesta viene rifiutata. Fornisci il campo channel e, quando necessario, un campo endpoint per disambiguare.

D: Come viene selezionata la conversazione quando esistono più thread?

Il sistema preferisce un thread aperto sullo stesso canale. Se non trovato, crea una nuova conversazione.

D: Come gestisco i duplicati quando eseguo un retry dopo un timeout?

Includi un idempotencyKey in ogni richiesta e riutilizzalo nei retry.

D: Posso recuperare in retroattivo messaggi inbound storici?

Sì. Fornisci metadata.timestamp con l'orario originale; il messaggio viene ordinato di conseguenza nella timeline.

D: Come indirizzo la location giusta se un contatto appare in più di una?

Usa credenziali o header collegati alla location/workspace desiderata. Le chiamate devono essere circoscritte alla location che possiede il contatto.