Come possiamo aiutarvi?

Integrazione di Webhook in entrata

TimelinesAI vi permette di automatizzare l'invio di messaggi WhatsApp in risposta a eventi o azioni negli strumenti che già utilizzate: CRM, assistenza, sistemi di reclutamento, ecc.

"Evento "Invia messaggio

È possibile ordinare a TimelinesAI di inviare un messaggio (con o senza file allegato) a un contatto specifico (può essere un gruppo). Se nell'area di lavoro sono collegati più account WhatsApp, è anche possibile specificare un particolare account WhatsApp da utilizzare per l'invio del messaggio.

Per impostare l'integrazione, il proprietario di uno spazio di lavoro deve accedere alla schermata "Integrazioni / Webhook in entrata" e generare un nuovo URL. Il sistema esterno deve inviare a tale URL un messaggio in un formato specifico (vedere i dettagli di seguito).

Limitazioni

  • La dimensione massima degli allegati è di 2 MB.
  • Non c'è una convalida immediata del formato del numero di telefono del destinatario o della connessione a WhatsApp. Passare all'interfaccia Timeline per verificare lo stato di invio/lettura dei messaggi.

Invio di file tramite webhook in entrata

Invio di un file: download diretto e servizi di hosting di file

È indispensabile inviare i file utilizzando i link di download diretto. Ciò consente al destinatario di ricevere effettivamente il file.

È opportuno utilizzare un servizio di hosting di file che fornisca un link diretto per il download. Il modo migliore per testare un link di questo tipo è la navigazione in incognito/privata, incollando il link nella barra di ricerca. Se il download del file inizia subito, il link è accettabile. Se invece viene visualizzata una qualsiasi pagina web, il link non può essere utilizzato per l'invio di file.

Il caso dei link al servizio di file hosting è che i file non possono essere scaricati. Ciò che viene scaricato e inviato è invece una pagina web di condivisione, che può portare a un file "corrotto".

Questo, a sua volta, si ripercuoterà sul vostro messaggio, in quanto i destinatari non potranno accedere ai media inviati, rendendo i file inutilizzabili. È quindi fondamentale assicurarsi di inviare link diretti per il download, che consentiranno ai destinatari di accedere al file senza problemi.

È possibile eseguire questo test anche inviando un messaggio webhook a uno dei numeri di test. Se dopo aver fatto clic sull'allegato viene visualizzato un messaggio di errore del tipo "File corrotto", "File incompatibile" o "Impossibile caricare il documento X", si tratta di un collegamento al servizio di hosting di file e deve essere sostituito con un collegamento di download diretto.

Utilizzo del credito

  • L'invio di un messaggio consuma 1 credito dalla quota di invio dei messaggi.
  • L'invio di un messaggio con testo e allegato non vuoto consuma 2 crediti dalla quota di invio dei messaggi.
  • Se non è possibile inviare un messaggio (numero WhatsApp non valido o non connesso, errore del server WhatsApp), la quota di invio dei messaggi verrà ripristinata (di solito entro un paio d'ore).

Velocità di invio dei messaggi

  • I messaggi saranno inviati con un ritardo casuale di circa 2 secondi tra i due messaggi (per evitare i meccanismi di rilevamento dello spam di WhatsApp).
  • Se si attivano webhook con frequenza inferiore a 2 secondi, i messaggi vengono accodati e inviati con ritardo. Ogni messaggio accodato consuma un credito di invio, quindi il numero di messaggi accodati non può superare la quota disponibile.

Configurazione e azioni dei webhook

  • "Webhook abilitato": consente di disabilitare il webhook senza rimuoverlo del tutto.
  • "Genera nuovo URL": creerà un nuovo URL univoco, che accetterà le notifiche. L'URL precedente non sarà più disponibile.
  • "Ultimi tentativi di invio": stato degli ultimi tentativi di attivazione del webhook
  • "Download log": un registro dettagliato degli ultimi 100 tentativi di attivazione, utile per risolvere i problemi di formattazione.

Formato della richiesta di webhook

Il Webhook accetta dati in formato JSON, tramite richiesta POST.

  • "action" (obbligatorio) - attualmente è supportato solo il valore "send".
  • "text" (obbligatorio) - un messaggio di testo semplice codificato UTF-8 da inviare (non è supportato il markdown, tranne il separatore di riga "\n"); può essere lasciato vuoto, se è specificato il file.
  • "file_url" (opzionale) - un URL accessibile al pubblico di un file che verrà scaricato e inviato come allegato.
  • "nome_file" (facoltativo) - un nome per l'allegato (deve essere fornito, se è specificato l'URL).

Il destinatario può essere specificato fornendo uno dei seguenti parametri:

  • "chat_id" - un id della chat come appare in TimelinesAI (può essere trovato nell'URL della pagina della chat o nel payload del webhook in uscita). Questo supporta l'invio di messaggi a un gruppo.
  • "jid" - un JID di WhatsApp che specifica il contatto o il gruppo
  • "phone" - un numero di telefono, formattato secondo lo standard internazionale dei numeri di telefono, ovvero:
    [+][prefisso del paese][prefisso della zona][numero di telefono locale] (ad esempio: +14151231234)
  • "nome_chat": il nome esatto della chat, come appare in TimelinesAI.

Se nell'area di lavoro sono collegati più account WhatsApp, utilizzare il seguente parametro aggiuntivo per specificare l'account WhatsApp da utilizzare:

  • "whatsapp account phone" (opzionale) - specifica (come numero di telefono, in formato internazionale) l'account WhatsApp da utilizzare per l'invio. Se omesso, per l'invio verrà utilizzato l'account WhatsApp attivo collegato più di recente nell'area di lavoro. Nota: se il parametro "chat_id" è specificato, "whatsapp account phone" non sarà considerato, perché ogni chat è già collegata a un account WhatsApp specifico.

Risposta Webhook

In caso di successo (la richiesta è stata convalidata e accettata per l'invio), il Webhook risponderà con lo stato HTTP 200 e JSON, contenente message_id del messaggio creato:

{
    "status": "success",
    "data": {
        "message_id": "wa_backend:3EB09FCC85FE99662E46"
    }
}

 

In caso di errore, il Webhook risponderà con lo stato HTTP 40X e JSON con i dettagli dell'errore, ad esempio:

{
"status": 40X,
"data": {},
"message": "Webhook not found"
}

Esempi

Esempio 1 - invio di un messaggio tramite un account WA specifico a un numero di telefono specifico:

{
"action": "send",
"whatsapp account phone" : "+15105566777", 
"phone": "+14151231234", 
"text": "lorem ipsum"
}

Esempio 2 - invio di un messaggio con testo e allegato a una chat (o gruppo) specificata da id:

{
"action": "send", 
"chat_id": "77234", 
"text": "lorem ipsum"
"file_url" : "https://timelines.ai/logo.png",
"file_name" : "logo.png"
}
Indice dei contenuti