Messaggi e conversazioni #

Le API dei messaggi ti consentono di inviare un messaggio a qualsiasi contatto, rileggere una conversazione, correggere o rimuovere un messaggio già inviato, reagire a un messaggio, recuperare l’intero thread di una sessione di chat, esportare una trascrizione e contrassegnare le chat come lette o non lette, il tutto senza aprire la posta in arrivo.

Tutti i percorsi in questa pagina sono relativi all’URL di base https://api.youraiconnector.com/v1. Ogni richiesta richiede la tua chiave API: consulta Autenticazione per l’elenco completo delle modalità di invio. Gli esempi seguenti utilizzano l’intestazione X-API-Key, con un esempio cURL che mostra anche il formato di query ?apiKey=.

Come funziona la consegna: L’invio di un messaggio non attende che arrivi a destinazione. L’API accetta il messaggio, risponde immediatamente con un ID messaggio e quindi lo consegna in background sul canale del contatto (WhatsApp, SMS, Instagram, ecc.). Per monitorare se un messaggio è stato effettivamente consegnato o letto, ascolta gli aggiornamenti di stato con i Webhook: non eseguire il polling. La risposta di invio conferma solo che il messaggio è stato accettato.

Inviare un messaggio #

Esistono due modi per inviare un messaggio. Scegli quello più adatto al modo in cui identifichi già il contatto:

• Invia tramite ID contatto — conosci già l’ID del contatto (ad esempio, hai creato il contatto tramite l’API o l’hai ottenuto da un webhook). Usa POST /contacts/{contactId}/send-message.
• Invia tramite identità del contatto — conosci il numero di telefono del contatto, l’ID Instagram, ecc., ma non il suo ID interno. Usa POST /contacts/send e lascia che la piattaforma trovi il contatto corretto.

Entrambi mettono in coda il messaggio allo stesso modo e lo consegnano sul canale in cui si trova il contatto. Non devi scegliere un trasporto: la piattaforma instrada i contatti WhatsApp su WhatsApp, i contatti SMS su SMS e così via.

Entrambi trovano solo contatti già esistenti. Nessuna delle due chiamate ne crea uno: un ID o un’identità che non corrispondono a nulla vengono restituiti come 404, non diventano un nuovo contatto. Quindi, se stai scrivendo a qualcuno per la prima volta, crea prima il contatto con POST /contacts oppure, su WhatsApp Web, usa Invia direttamente a un numero WhatsApp Web qui sotto, che crea il contatto nella stessa chiamata.

Invia tramite ID contatto #

POST /contacts/{contactId}/send-message

Su LinkedIn, un messaggio inviato in questo modo, o dalla posta in arrivo, viene recapitato anche mentre una persona sta gestendo la conversazione sul lato LinkedIn. Le risposte dell’IA e i suoi follow-up vengono trattenuti in tale conversazione. Una risposta trattenuta viene rimossa dalla chat invece di essere mostrata come fallita, poiché non è stato inviato nulla e non viene utilizzato alcun credito. L’ultima risposta dell’IA prima di passare la conversazione a una persona viene comunque recapitata.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi! Your appointment is confirmed for tomorrow at 10:00."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi! Your appointment is confirmed for tomorrow at 10:00.",
    }),
  }
);
const data = await res.json();
console.log(data.messageId);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Hi! Your appointment is confirmed for tomorrow at 10:00."},
)
print(res.json()["messageId"])

Risposta (200 OK):

{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}

Invia tramite identità del contatto #

POST /contacts/send

Utilizza questo metodo quando non disponi dell’ID interno del contatto. Fornisci il body del messaggio più o un contact_id, o un channel insieme al campo di identità che corrisponde a quel canale.

Quali canali possono essere risolti tramite identità. Solo sei dei 14 accettano un campo di identità invece di un contact_id: whatsapp, whatsapp_web e sms vengono cercati tramite phone_number, instagram tramite instagram_id, messenger tramite messenger_id e telegram tramite telegram_user_id. Gli altri otto — instagram_private, chat-widget, custom, email, line, imessage, linkedin e viber — non hanno un’identità pubblica da ricercare, quindi l’invio su tali canali richiede contact_id; passare solo channel restituisce un 400 che indica che contact_id è richiesto.

cURL (utilizzando il formato di query ?apiKey=)

curl -X POST "https://api.youraiconnector.com/v1/contacts/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "body": "Hi! Your appointment is confirmed."
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    phone_number: "+31612345678",
    body: "Hi! Your appointment is confirmed.",
  }),
});
const data = await res.json();
console.log(data.message_id, data.channel);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/send",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "phone_number": "+31612345678",
        "body": "Hi! Your appointment is confirmed.",
    },
)
data = res.json()
print(data["message_id"], data["channel"])

Risposta (201 Created):

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp"
}

Perché un messaggio potrebbe essere rifiutato: Un contatto con la modalità non disturbare o privata attivata non può ricevere messaggi in uscita — la richiesta fallisce con un 422. Se nessun contatto corrisponde all’ID o all’identità fornita, si ottiene un 404.

Invio su WhatsApp Web: variazioni e protezione dai burst #

Due aspetti si applicano a body quando il contatto utilizza WhatsApp Web.

Le parentesi Spintax vengono espanse a ogni invio. Un body di {Hi|Hello|Hey} there, quick question viene inviato come uno dei tre saluti, scelto per quello specifico invio: le parentesi non raggiungono mai il contatto. Usale per fornire a ogni contatto un messaggio di apertura diverso dallo stesso codice di integrazione. Il testo senza parentesi viene inviato esattamente come scritto.

I burst di messaggi di apertura identici vengono rifiutati. Se dieci messaggi di apertura quasi identici partono da un numero WhatsApp Web entro un’ora, verso contatti che non ti hanno mai scritto, quelli successivi non vengono consegnati: l’invio viene accettato come di consueto (riceverai comunque un messageId), ma il messaggio rimarrà con status: "failed" e error_code: "opener_burst", accompagnato da una motivazione leggibile dal cliente. Riprovare con lo stesso testo non serve: varia il testo, attendi un’ora e invia di nuovo. Le risposte all’interno di conversazioni esistenti non sono mai interessate. La spiegazione è disponibile in I messaggi di apertura identici portano alla limitazione dei numeri.

Invia direttamente a un numero WhatsApp Web #

POST /whatsapp-web/send

Invia a un numero di telefono su WhatsApp Web senza dover prima cercare un contatto. Se il numero non è ancora un contatto, questo viene creato nella stessa chiamata, con l’IA disattivata per esso, in modo che il messaggio appaia come inviato manualmente e nessun assistente prenda il controllo della conversazione in seguito. Un contatto esistente viene riutilizzato così com’è.

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-web/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "message": "Hi Alex, your quote is ready."
  }'

Una chiamata riuscita risponde con 202:

{ "success": true, "queued": true, "contactId": "abc123" }

202 significa accettato, non ancora consegnato. Al di fuori degli orari di attività, l’invio viene trattenuto e parte nel primo slot consentito, a meno che non sia stato passato ignoreActiveHours. Leggi lo stato del messaggio con Elenca i messaggi di un contatto utilizzando l’contactId ottenuto qui.

Quando l’invio non va a buon fine:

Una seconda chiamata per lo stesso contatto mentre un invio è ancora in attesa risponde con 409, in modo che non si accumuli mai una coda dietro una singola persona.

Registra una nota in una conversazione #

POST /contacts/notes

Aggiunge una riga alla conversazione di un contatto senza inviarla. Usala per il contesto che il tuo team e l’IA dovrebbero avere, ma che il contatto non dovrebbe mai ricevere: un riepilogo di una telefonata appena effettuata dal tuo assistente vocale, un’osservazione dal tuo CRM o una nota di un collega. Funziona su ogni canale (WhatsApp, SMS, Instagram, Messenger, Telegram, il widget della chat, canali personalizzati e così via).

Cosa succede a una nota:

• Viene visualizzata nella chat nella posta in arrivo come una scheda Nota gialla, con l’autore se ne hai indicato uno.
• L’IA la legge come parte della cronologia della conversazione, contrassegnata come nota interna, in modo che la sua risposta successiva ne tenga conto.
• Non viene mai inviata al contatto, non comporta costi di crediti di messaggi e non attiva nulla: nessuna risposta dell’IA, nessuna automazione, nessun webhook, nessuna notifica, nessun badge di messaggio non letto. Non mette in pausa l’IA e non conta come una risposta da parte del tuo team.

Trova il contatto nello stesso modo di Invia tramite identità del contatto: ovvero il suo ID, o un channel più l’identificativo corrispondente. Una nota viene inviata solo a un contatto già esistente; se non c’è corrispondenza, si ottiene un 404.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "author": "Voice agent",
    "body": "Voice call, 3:12. Asked about knee surgery waiting times, prefers a call back on Tuesday morning.",
    "external_id": "call_8f2k1"
  }'

Risposta (201, o 200 con duplicate: true quando il external_id era già stato registrato)

{
  "success": true,
  "messageId": "note_4c1f0e...",
  "contactId": "contact123"
}

Una nota appare in Elenca i messaggi di un contatto con type: "note".

Genera una bozza di risposta con l’IA #

POST /contacts/{contactId}/draft-reply

Chiede all’agente IA che gestisce una conversazione di scrivere la risposta successiva e ti restituisce il testo. Non viene inviato nulla. È la stessa bozza che scrive il pulsante Genera risposta nella posta in arrivo: l’agente utilizza la sua configurazione, la sua base di conoscenza e la conversazione finora, e risponde nella lingua del contatto. Usalo per inserire un essere umano (o la tua app) tra l’IA e il contatto: recupera la bozza, mostrala per l’approvazione, quindi inviala con Invia tramite ID contatto, modificata o così com’è.

• La bozza viene scritta dall’agente assegnato al contatto. Un contatto che non ha ancora un agente riceve l’agente che risponderebbe al suo prossimo messaggio.
• Durante la stesura, l’agente non esegue alcuno strumento o funzione, quindi non avviene alcuna prenotazione, etichettatura, trasferimento o altra azione.
• Non viene memorizzato nulla nella conversazione e il contatto non vede nulla.
• Una bozza costa gli stessi crediti di una risposta IA da parte di quell’agente in questa conversazione, e nulla quando è collegata la tua chiave IA.
• La conversazione deve contenere almeno un messaggio.

Tutti i campi del corpo sono facoltativi; un corpo vuoto (o nessun corpo) redige la risposta successiva.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/draft-reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Offer Tuesday at 3pm for the consultation" }'

Risposta (200)

{
  "success": true,
  "contact_id": "contact123",
  "draft": "Hi Sara, Tuesday at 3pm works for the consultation. Shall I put you down for it?"
}

Un 400 significa che la conversazione non ha ancora messaggi, i tuoi crediti sono esauriti o il contatto non ha un agente o una campagna da cui redigere ( error indica quale). Un 404 significa che il contatto non esiste o che la chiave di un membro del team è limitata ai contatti che non può vedere. La chiave o il membro del team deve avere l’autorizzazione per modificare i messaggi.

Utilizzi un client IA tramite MCP? La stessa azione è disponibile come strumento generate_reply_draft.

Elenca i messaggi di un contatto #

GET /contacts/{contactId}/messages

Restituisce i messaggi di un contatto, dal più recente, con paginazione basata su cursore.

Nota sul filtraggio e la paginazione: I filtri filter e direction vengono applicati a ogni pagina dopo la lettura, quindi una pagina filtrata può contenere meno elementi di limit. Il next_cursor avanza comunque attraverso l’intera conversazione, quindi continua la paginazione finché next_cursor non è null.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&direction=inbound" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ limit: "50", direction: "inbound" });
const res = await fetch(
  `https://api.youraiconnector.com/v1/contacts/contact123/messages?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.messages, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
)
data = res.json()
print(data["messages"], data["next_cursor"])

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T10:00:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ],
  "next_cursor": "cD4eF6gH8iJ0kL2mN3oP"
}

Campi del messaggio #

Scarica l’allegato di un messaggio #

POST /chat-exports/media/download-url

Fornisce un nuovo link di download per il file allegato a un messaggio: un’immagine, un messaggio vocale, un video o un documento. Il link è valido per 1 ora. Usalo quando vuoi salvare gli allegati altrove (ad esempio, per archiviare CV o messaggi vocali inviati da un contatto), o quando il media_url su un messaggio o un webhook di Nuovo Messaggio non si apre più.

Per trovare messaggi con allegati, elenca i messaggi di un contatto con filter=media. Il id di ogni messaggio e l’ID del contatto formano il messagePath.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/media/download-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/chat-exports/media/download-url", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ messagePath: "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO" }),
});
const { data } = await res.json();
console.log(data.url); // download the file within the hour

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/chat-exports/media/download-url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"},
)
file_url = res.json()["data"]["url"]

Risposta (200 OK):

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresInMs": 3600000
  }
}

Utilizzi un client AI tramite MCP? La stessa azione è disponibile come strumento get_chat_media_download_url.

Elenca sessioni di chat #

Una sessione di chat è una finestra di conversazione con un contatto. Si apre al primo messaggio in arrivo quando non c’è alcuna sessione aperta e si chiude automaticamente 48 ore dopo l’ultimo messaggio in arrivo del contatto (ogni nuovo messaggio in arrivo posticipa la chiusura di altre 48 ore). L’IA che conclude una chat non chiude la sessione; attiva solo il webhook Chat Concluded. Le sessioni sono il modo in cui suddividi una lunga cronologia in conversazioni leggibili invece di un unico elenco infinito.

Sessioni recenti per tutti i contatti #

GET /chat-sessions/recent

Restituisce le sessioni iniziate nelle ultime X ore, dalla più recente, per ogni contatto sull’account.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/recent?hours=24&status=ChatSessionClosed" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ hours: "24", status: "ChatSessionClosed" });
const res = await fetch(`https://api.youraiconnector.com/v1/chat-sessions/recent?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data.total_sessions, data.data.sessions);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-sessions/recent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hours": 24, "status": "ChatSessionClosed"},
)
data = res.json()["data"]
print(data["total_sessions"], data["sessions"])

Risposta (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_sessions": 2,
    "sessions": [
      {
        "session_id": "session456",
        "contact_id": "contact123",
        "contact_name": "Jane Doe",
        "contact_phone": "+31612345678",
        "contact_email": "jane@example.com",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

Tutte le sessioni per un singolo contatto #

GET /chat-sessions/{contactId}

Restituisce ogni sessione di chat per un singolo contatto. Stessi parametri status, limit e includeMessages di cui sopra: hours non si applica qui.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/contact123?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta (200 OK):

{
  "success": true,
  "data": {
    "contact_id": "contact123",
    "contact_name": "Jane Doe",
    "total_sessions": 2,
    "sessions": [
      {
        "id": "session456",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

I nomi dei campi ID sessione differiscono tra i due endpoint. L’elenco delle sessioni recenti lo chiama session_id (contiene anche i dettagli del contatto, poiché le sessioni provengono da molti contatti); l’elenco per contatto lo chiama id. Entrambi i valori sono ciò che passi come {sessionId} quando recuperi l’intero thread qui sotto.

Quando includeMessages=true, ogni sessione ottiene un array messages le cui voci contengono id, body, direction, timestamp, type, channel e status.

Recupera un thread di sessione chat #

GET /contacts/{contactId}/chat-sessions/{sessionId}/messages

Una sessione di chat raggruppa i messaggi di un contatto in un’unica finestra di conversazione. Questo endpoint restituisce l’intero thread di una singola sessione, dal più vecchio al più recente, insieme ai metadati della sessione. È possibile trovare gli ID delle sessioni per un contatto tramite gli endpoint delle sessioni di chat.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.session, data.messages);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["session"], data["messages"])

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "session": {
    "id": "session456",
    "status": "ChatSessionClosed",
    "start_date_time": "2026-06-01T09:55:00.000Z",
    "end_date_time": "2026-06-01T10:20:00.000Z",
    "tag": "Booking enquiry"
  },
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T09:55:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ]
}

L’oggetto session riporta status (ChatSessionOpened se attiva, ChatSessionClosed una volta terminata), start_date_time, end_date_time e un tag leggibile dall’utente. L’array messages utilizza gli stessi campi del messaggio dell’endpoint di elenco.

Modifica, elimina e reagisci ai messaggi #

Questi endpoint modificano un messaggio dopo che è stato inviato. Due di essi raggiungono il canale del contatto oltre alla tua copia, quindi leggi l’introduzione della sezione prima di implementarli: ciò che è possibile dipende interamente dal canale su cui si trova la conversazione.

Cosa consente ogni canale

Su ogni altro canale — WhatsApp Business API, SMS, Instagram, Messenger, email, LINE, canali personalizzati — un’eliminazione rimuove comunque il messaggio dalla tua casella di posta, ma il contatto mantiene la propria copia, e la modifica o la reazione non sono affatto possibili.

Modifica un messaggio #

POST /contacts/{contactId}/messages/{messageId}/edit

Riscrive un messaggio che hai già inviato, sul dispositivo del contatto e nella tua copia.

A differenza dell’eliminazione, questa operazione fallisce in modo evidente quando il canale rifiuta: riceverai un 409 e la tua copia rimarrà esattamente come quella del contatto, poiché mostrare una modifica mai ricevuta creerebbe una discrepanza tra le due parti. Il campo edit_reason ti spiega il motivo: la finestra di modifica del canale è scaduta, il canale è disconnesso, il messaggio contiene un allegato che il canale non può modificare (media_not_editable: su WhatsApp Web è possibile modificare solo i messaggi di testo, non il testo sotto una foto, un video o un file), o si è verificato un altro problema.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Sorry - I meant Thursday at 3pm." }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ body: "Sorry - I meant Thursday at 3pm." }),
  }
);
const data = await res.json();
console.log(data.edited, data.edit_reason);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Sorry - I meant Thursday at 3pm."},
)
data = res.json()
print(data.get("edited"), data.get("edit_reason"))

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "edited": true,
  "edit_reason": "edit_dispatched"
}

Se il canale non accetta la modifica, ricevi invece un 409 e nulla viene modificato:

{
  "success": false,
  "error": "The message could not be edited",
  "edit_reason": "channel_disconnected"
}

Un messaggio che è già stato eliminato, un canale che non può affatto modificare e un messaggio troppo vecchio per il suo canale restituiscono tutti 400 — la richiesta non raggiunge mai il canale.

Elimina un messaggio #

DELETE /contacts/{contactId}/messages/{messageId}

Rimuove il messaggio dalla tua conversazione e, dove il canale lo consente, ritira anche la copia del contatto. Nessun corpo della richiesta.

Questa operazione risponde sempre 200 quando il messaggio esisteva, anche se la copia del contatto non poteva essere ritirata — la tua copia è sparita, quindi un errore sarebbe fuorviante. Leggi i tre campi nella risposta per comunicare all’utente cosa è successo realmente:

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.revoked, data.revoke_reason);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["revoked"], data["revoke_reason"])

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "revoke_supported": true,
  "revoked": true,
  "revoke_reason": "revoke_dispatched"
}

I messaggi eliminati non vengono rimossi dalla cronologia della conversazione. Rimangono in GET /contacts/{contactId}/messages con is_deleted: true e un body vuoto e media_url.

Eliminare più messaggi contemporaneamente #

POST /contacts/{contactId}/messages/bulk-delete

Cancella un gruppo di messaggi solo dal tuo lato. I corpi e gli allegati vengono svuotati, ma nulla viene ritirato sul dispositivo del contatto: per ritirare anche un messaggio, eliminalo uno alla volta con l’endpoint per singolo messaggio qui sopra.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": ["msg_1", "msg_2"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message_ids: ["msg_1", "msg_2"] }),
  }
);
console.log((await res.json()).deleted);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["msg_1", "msg_2"]},
)
print(res.json()["deleted"])

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "deleted": 2
}

Reagire a un messaggio #

POST /contacts/{contactId}/messages/{messageId}/react

Inserisce la tua reazione emoji su un messaggio, o la rimuove inviando una stringa vuota. Le reazioni del contatto non vengono mai toccate.

Come per la modifica, questa operazione fallisce invece di mostrare una reazione che il contatto non ha mai ricevuto, e l’errore ti indica se vale la pena riprovare:

• 422 — non può mai essere consegnata in questa conversazione: il canale non supporta le reazioni, il messaggio non ha un ID lato canale, o l’emoji è al di fuori del set consentito dal canale.
• 409 — il canale era momentaneamente irraggiungibile. Un nuovo tentativo potrebbe funzionare.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emoji: "👍" }),
  }
);
const data = await res.json();
console.log(data.reactions);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"emoji": "👍"},
)
print(res.json()["reactions"])

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "reaction_supported": true,
  "reaction_reason": "reaction_dispatched",
  "reactions": [
    {
      "emoji": "👍",
      "from_phone_number": "+31612345678",
      "from_me": true,
      "reacted_at": "2026-06-01T10:05:00.000Z"
    }
  ]
}

L’array reactions è l’insieme completo delle reazioni presenti sul messaggio, le tue e quelle del contatto. In caso di 409 o 422 viene restituito invariato, quindi un client che esegue il rendering direttamente da esso non mostrerà mai una reazione che non è stata consegnata.

Valutare o aggiungere un messaggio ai preferiti #

PATCH /contacts/{contactId}/messages/{messageId}

Valuta un messaggio con pollice in su o in giù e/o lo contrassegna come importante. Si tratta di una gestione contabile solo dal tuo lato: nulla viene inviato al contatto.

Invia almeno uno dei due, altrimenti riceverai un 400. Viene scritto solo ciò che invii, quindi aggiungere una stella a un messaggio non rimuove mai la sua valutazione e viceversa — e la risposta riporta solo i campi che hai inviato.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "score": 1, "is_important": true }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ score: 1, is_important: true }),
});

Python

import requests

requests.patch(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"score": 1, "is_important": True},
)

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "score": 1,
  "is_important": true
}

Contrassegna i messaggi come letti #

È possibile rimuovere lo stato di non letto per messaggi specifici o per l’intera conversazione.

Contrassegna messaggi specifici come letti #

POST /contacts/{contactId}/messages/mark-read

Passa gli ID dei messaggi da contrassegnare come letti.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message_ids: ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"],
    }),
  }
);
const data = await res.json();
console.log(data.marked_read);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]},
)
print(res.json()["marked_read"])

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "marked_read": 2
}

Contrassegna l’intera chat come letta #

POST /contacts/{contactId}/mark-read

Rimuove l’indicatore di non letto per l’intera conversazione del contatto nella posta in arrivo. Non è richiesto alcun corpo della richiesta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-read" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

Contrassegna l’intera chat come non letta #

POST /contacts/{contactId}/mark-unread

Ripristina l’indicatore di non letto sulla conversazione: utile quando qualcuno del tuo team ha aperto una chat ma la sta passando a qualcun altro. Non è richiesto alcun corpo della richiesta.

Questo è un flag valido solo per la posta in arrivo: non modifica l’orario dell’ultima lettura della conversazione, quindi non viene inviata alcuna conferma di lettura al contatto sui canali che le supportano.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-unread" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

Esporta una conversazione #

Le esportazioni forniscono un’intera conversazione come trascrizione leggibile, invece di sfogliare i messaggi pagina per pagina. Ogni endpoint di esportazione accetta un filter di all (predefinito), text, media o tool_use, che corrisponde al filtro nell’elenco dei messaggi.

Esporta la chat di un contatto #

GET /chat-exports/{contactId}

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/contact123?format=json" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-exports/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"format": "json"},
)
print(res.json()["data"]["messages"])

Risposta con format=json (200 OK):

{
  "success": true,
  "data": {
    "contact": {
      "id": "contact123",
      "name": "Jane Doe",
      "phone": "+31612345678",
      "email": "jane@example.com"
    },
    "messages": [
      {
        "body": "Hi! I have a question about my order.",
        "direction": "inbound",
        "timestamp": "2026-06-01T09:55:00.000Z",
        "type": "text",
        "media_url": null,
        "media_content_type": null,
        "name": null,
        "args": null
      }
    ]
  }
}

Con format=txt (il predefinito), data è invece un link per il download del file di trascrizione generato:

{
  "success": true,
  "data": "https://storage.googleapis.com/.../chat-export-contact123-....txt"
}

Il link per il download ha una durata limitata. Recupera il file non appena ricevi il link invece di memorizzarlo: richiedi una nuova esportazione quando hai di nuovo bisogno della trascrizione.

Esporta ogni conversazione recente #

GET /chat-exports/recent

Esporta le conversazioni di tutti i contatti che sono stati attivi nelle ultime X ore, in un’unica chiamata.

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/recent?hours=24&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_contacts": 2,
    "exports": [
      {
        "contactId": "contact123",
        "contactName": "Jane Doe",
        "phoneNumber": "+31612345678",
        "email": "jane@example.com",
        "messageCount": 12,
        "chatExport": "Acme Export - Jane Doe\nPhone: +31612345678\n..."
      }
    ]
  }
}

Con format=txt la risposta è il file di testo stesso, inviato come download anziché come JSON.

Questa singola chiamata estrae l’intera cronologia di ogni contatto corrispondente, quindi mantieni hours e limit moderati su account molto attivi.

Invia una trascrizione via email al contatto #

POST /chat-exports/{contactId}/email

Invia al contatto la propria trascrizione della conversazione via email: il flusso “inviami questa chat via email”, gestito dal tuo sistema.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/contact123/email" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Here is a copy of our chat, as promised." }'

Risposta (200 OK):

{
  "success": true,
  "data": {
    "via": "transactional",
    "recipientEmail": "jane@example.com",
    "messageCount": 42,
    "omittedCount": 0
  }
}

omittedCount ti indica quanti dei messaggi più vecchi sono stati esclusi per mantenere l’email di una lunghezza ragionevole. Un 200 significa che la trascrizione è stata creata e messa in coda per l’invio, non che sia già arrivata nella casella di posta.

Sospendere o riprendere l’IA per un singolo contatto #

PUT /contacts/{contactId}

Imposta is_bot_active su false per impedire all’IA di rispondere a un contatto, e riportalo su true per restituire la conversazione. Questo è l’interruttore di controllo che ti serve quando un essere umano interviene in una conversazione: i messaggi in uscita inviati tramite API vengono comunque consegnati mentre il bot è in pausa.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/contacts/contact123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_bot_active": false }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ is_bot_active: false }),
});

Python

import requests

requests.put(
    "https://api.youraiconnector.com/v1/contacts/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_bot_active": False},
)

Risposta

{
  "success": true,
  "contact_id": "contact123"
}

Sospensione durante la risposta

Se un umano sta prendendo il controllo inviando una risposta, puoi mettere in pausa il bot nella stessa richiesta invece di effettuare una seconda chiamata. POST /contacts/{contactId}/send-message accetta questi flag opzionali:

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, Sarah here - taking over from the assistant.",
    "pauseBot": true,
    "clearIncompleteReply": true,
    "human_reply": true
  }'

La risposta include "botPaused": true quando la pausa è stata applicata.

Contrassegnare un contatto come privato con POST /contacts/bulk-flag sospende anche il bot per quel contatto. Vedi Contatti per l’elenco completo dei campi.

Creare la propria casella di posta #

Tutto ciò di cui una casella di posta ha bisogno si trova in questa pagina e in Contatti:

Per aggiornamenti in tempo reale, iscriviti agli eventi New Message, Replies, Human Alerted e Chat Concluded con i Webhook invece di interrogare questa API a intervalli regolari.

Errori dell’API Messaggi #

Gli endpoint dei messaggi restituiscono il pacchetto di errore standard:

{
  "success": false,
  "error": "Contact not found"
}

I codici condivisi che ogni endpoint può restituire — 401, 403 (il tuo piano non include l’accesso all’API), 429 (limite di frequenza) e 500 — sono elencati con indicazioni sui tentativi in Errori e Paginazione.

Passaggi successivi #

• Webhooks — ricevi aggiornamenti sullo stato di consegna invece di eseguire il polling.
• Contatti — crea e cerca i contatti a cui invii messaggi.
• Appuntamenti — prenota e gestisci gli appuntamenti per i tuoi contatti.