Messaging & email

Il gruppo Messaging & email copre l'invio e il monitoraggio delle comunicazioni: le conversazioni chat, i template WhatsApp approvati, l'invio di messaggi WhatsApp/SMS e la lettura dello stato di un messaggio o di un'email inviata via Audin Mail.

Le risorse

Tutte le rotte richiedono l'header X-API-Key. Lo schema completo resta sullo Swagger.

Inviare un messaggio

POST /messages/send invia un messaggio WhatsApp o SMS a un numero. Se il numero non esiste ancora nel tuo Account, il lead e la conversazione vengono creati automaticamente. Campi del body:

curl -X POST https://api.audin.ai/messages/send \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+393334445566",
    "channel": "WHATSAPP",
    "type": "template",
    "templateId": "<whatsapp-template-id>",
    "templateVars": { "1": "Mario" }
  }'

const res = await fetch("https://api.audin.ai/messages/send", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AUDIN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+393334445566",
    channel: "WHATSAPP",
    type: "template",
    templateId: whatsappTemplateId,
    templateVars: { "1": "Mario" },
  }),
});
const { data } = await res.json(); // { messageId, conversationId, status }

La risposta riporta messageId, conversationId e lo status iniziale (PENDING o SENT). Lo status finale (consegna, lettura, errore) si legge poi con GET /messages/{id}.

Stato di un messaggio

GET /messages/{id} (usa il messageId ritornato dall'invio) restituisce stato e metadati completi del messaggio, inclusi gli eventuali allegati.

Campi rilevanti della risposta:

• status — uno tra PENDING, SENT, DELIVERED, READ, FAILED.
• direction — INBOUND (dal cliente) o OUTBOUND (verso il cliente).
• deliveredAt, readAt — timestamp degli eventi (quando disponibili).
• media — array di allegati; ogni elemento espone un signedUrl temporaneo (TTL ~1 ora) per scaricare il file.
• conversation — riepilogo della conversazione di appartenenza (canale, stato, conteggio messaggi).

curl "https://api.audin.ai/messages/<messageId>" \
  -H "X-API-Key: $API_KEY"

const res = await fetch(`https://api.audin.ai/messages/${messageId}`, {
  headers: { "X-API-Key": process.env.AUDIN_API_KEY },
});
const message = await res.json();
console.log(message.status); // PENDING | SENT | DELIVERED | READ | FAILED

// Gli allegati espongono un URL firmato temporaneo (TTL ~1h)
for (const m of message.media ?? []) {
  console.log(m.fileName, m.signedUrl);
}

Conversazioni e template WhatsApp

• GET /conversations elenca le conversazioni dell'Account (webchat, WhatsApp, widget). Da una conversazione puoi leggere i messaggi (GET /conversations/{id}/messages), inviare (POST /conversations/{id}/send) o effettuare un human takeover.
• GET /whatsapp-templates (e GET /whatsapp-templates/approved/list per i soli approvati) elenca i template WhatsApp disponibili; usa l'id di un template approvato come templateId in POST /messages/send.

Inviare in una conversazione esistente

POST /conversations/{id}/send invia un messaggio testo o template in una conversazione già identificata dal suo id (a differenza di POST /messages/send, che risolve o crea il lead a partire dal numero). È JSON-only: per gli allegati usa POST /conversations/{id}/attachments.

Permesso richiesto: Conversation:UPDATE. Body { content?, templateId?, templateVars? } — almeno uno tra content (testo free-form) e templateId (template approvato) è obbligatorio.

curl -X POST https://api.audin.ai/conversations/<conversationId>/send \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Buongiorno, la richiamiamo a breve."
  }'

Inviare allegati

Gli allegati (immagini, documenti, audio, video) si inviano con endpoint multipart dedicati (campi form, non JSON). Ne esistono due, a seconda che tu abbia già una conversazione o solo un numero:

• POST /conversations/{id}/attachments — in una conversazione esistente.
• POST /messages/send-attachments — direttamente a un numero (Audin risolve o crea lead e conversazione, come POST /messages/send).

Permesso richiesto in entrambi i casi: Conversation:UPDATE.

WhatsApp consente 1 media per messaggio: con più file Audin invia una sequenza di N messaggi (uno per allegato) con una sola chiamata — non devi orchestrarlo tu.

# Più allegati: 3 messaggi, il testo accompagna l'ultimo
curl -X POST https://api.audin.ai/conversations/<conversationId>/attachments \
  -H "X-API-Key: $API_KEY" \
  -F "file=@/path/to/foto1.jpg" \
  -F "file=@/path/to/foto2.jpg" \
  -F "file=@/path/to/preventivo.pdf" \
  -F "content=In allegato le foto e il preventivo"

curl -X POST https://api.audin.ai/messages/send-attachments \
  -H "X-API-Key: $API_KEY" \
  -F "to=+393334445566" \
  -F "channel=WHATSAPP" \
  -F "file=@/path/to/foto1.jpg" \
  -F "file=@/path/to/preventivo.pdf" \
  -F "content=In allegato la foto e il preventivo"

Vincoli sugli allegati (validi per entrambi gli endpoint):

• 1 media per messaggio (limite WhatsApp); più file ⇒ più messaggi, max 10 per richiesta.
• Tipi ammessi: immagini JPEG/PNG/WebP, PDF, DOC/DOCX, audio MP3/OGG/AMR, video MP4/3GPP.
• Dimensione massima: 16 MB per file.
• Con saveToDrive=true i file restano archiviati nel Drive dell'Account; con false (default) sono effimeri e rimossi dopo la consegna.

La risposta è un riepilogo per-file (data.sent, data.total, data.partial, data.messages[] con fileName, status SENT/FAILED/SKIPPED e messageId/error). Status: 200 = tutti inviati, 207 = invio parziale (partial: true), 502 = nessuno inviato.

Leggere i messaggi e gli allegati ricevuti

GET /conversations/{id}/messages elenca i messaggi della conversazione (dal più vecchio al più recente; limit e beforeId per la paginazione). Ogni messaggio espone in media[] gli allegati inviati e ricevuti: ciascun elemento ha url (signed URL temporaneo, null se l'allegato effimero è già stato rimosso), mediaType (IMAGE/VIDEO/AUDIO/DOCUMENT), mimeType, fileName e deletedAt.

curl "https://api.audin.ai/conversations/<conversationId>/messages?limit=50" \
  -H "X-API-Key: $API_KEY"

Stato di un'email (Audin Mail)

GET /emails/{id} restituisce lo stato corrente di un'email inviata via Audin Mail, con i timestamp di ogni evento del ciclo di vita.

Campi rilevanti della risposta:

• status — uno tra PENDING, SENT, DELIVERED, OPENED, CLICKED, BOUNCED, FAILED, DROPPED.
• sentAt, deliveredAt, openedAt, clickedAt, bouncedAt — timestamp degli eventi corrispondenti (valorizzati man mano che avvengono).
• toEmail, toName — destinatario.
• template — il template risolto (source account o system), oppure null se l'email non era basata su template.

curl "https://api.audin.ai/emails/<emailLogId>" \
  -H "X-API-Key: $API_KEY"

const res = await fetch(`https://api.audin.ai/emails/${emailLogId}`, {
  headers: { "X-API-Key": process.env.AUDIN_API_KEY },
});
const email = await res.json();
// PENDING | SENT | DELIVERED | OPENED | CLICKED | BOUNCED | FAILED | DROPPED
console.log(email.status, email.openedAt);

Prossimo passo