API SMS

Con Contact Center AI Platform (CCAI Platform), puoi utilizzare l'API SMS per gestire i messaggi SMS in entrata e in uscita.

Autenticazione

Per utilizzare l'API SMS, devi disporre di una credenziale.

Per creare una credenziale per l'API SMS, segui questi passaggi:

  1. Nel portale della piattaforma CCAI, fai clic su Impostazioni > Impostazioni sviluppatore > Gestione delle credenziali API.

  2. Fai clic sul pulsante + Aggiungi credenziale API. Viene visualizzato un messaggio Aggiungi credenziale API.

  3. Inserisci un nome per la credenziale.

  4. Fai clic su Crea.

API SMS in uscita

L'API SMS in uscita fornisce un endpoint per l'invio di messaggi SMS in uscita. In questo modo puoi inviare messaggi SMS ai consumatori in modo programmatico.

Quando utilizzi questa API, devi tenere presente tre punti chiave:

  • Questo servizio non è progettato per inviare decine di migliaia di messaggi contemporaneamente. L'obiettivo è la messaggistica basata sugli eventi.

  • I consumatori possono rispondere al messaggio SMS e avviare una sessione di assistenza.

  • Questa API non funziona se devi inviare più SMS allo stesso numero nello stesso giorno.

Casi d'uso

I casi d'uso di esempio dell'API SMS in uscita sono basati sugli eventi. Ad esempio, se vuoi comunicare al consumatore che il suo ordine è pronto per il ritiro E offrirgli la possibilità di rispondere. Una sessione attiva viene creata quando viene inviato un SMS in uscita; quando il cliente risponde, viene indirizzato a un agente.

La differenza tra questa API e l'API Sessionless Outbound SMS è che con quest'ultima invii solo la notifica e, se il consumatore risponde, riceve un messaggio predefinito (se configurato) e non viene indirizzato a un agente.

Altri potenziali casi d'uso:

  • Accesso all'account.
  • Attività dell'account.
  • Eventi importanti relativi all'utilizzo dell'account.
  • Rilevamento di problemi del dispositivo connesso.
  • Notifiche dell'orario di arrivo stimato per i servizi on demand, come consegne e corse condivise.
  • Promemoria per appuntamenti.
  • Avvisi proattivi relativi al servizio o all'account.
  • Autenticazione a due fattori (richiede che il cliente disponga di un generatore di codici e di una procedura di servizio esistenti).

Endpoint API SMS in uscita

L'URI di base per questo nuovo endpoint è:

POST https://<subdomain>.<domain>/apps/api/v1/sms

Supporto SMS in entrata

Se un ambiente vuole supportare le risposte SMS in entrata, il numero in uscita deve essere configurato anche come numero SMS in entrata assegnato a una coda. Ogni numero di telefono per SMS può essere assegnato a una sola coda. Per saperne di più, consulta Configurazione generale della chat SMS.

Se un utente finale risponde a un SMS configurato in questo modo, verrà indirizzato al menu della coda SMS a cui è assegnato il numero di telefono SMS in entrata. Per saperne di più, consulta la sezione Impostazioni di Chat per i messaggi SMS - Numero di telefono.

Operazioni API

Questa sezione descrive le operazioni API, i parametri del corpo e i codici di risposta.

Body and Params

I seguenti campi devono essere inclusi nel corpo della richiesta API:

Nome campo Tipo Obbligatorio Descrizione Valori Note
agent_id Numero intero No L'agente corrispondente a questo ID verrà assegnato a una nuova chat se non esiste una chat tra i numeri forniti. Se l'agente è connesso a una chat esistente, il messaggio verrà inviato per suo conto.
agent_email Stringa No L'indirizzo email dell'agente.
chat_type Stringa Sì SMS SMSAP
chat_subtype Stringa Sì api_initiated
end_user_number Stringa Sì Numero a cui inviare l'SMS Validazione: numero di telefono valido: +18882468888 per un numero di telefono statunitense
outbound_number Stringa Sì Numero di telefono in uscita da utilizzare per l'invio del messaggio SMS Convalida: a) il numero di telefono deve essere un numero di telefono per SMS associato all'inquilino, b) numero di telefono mancante, c) formato del numero di telefono errato: +18882468888 per un numero di telefono statunitense
messaggio Stringa Sì Messaggio SMS da inviare al consumatore Messaggi lunghi: dividi i messaggi lunghi in più messaggi (questa funzionalità dovrebbe essere coperta dalla funzionalità SMS in uscita esistente) Convalida: a) messaggio mancante, b) messaggio che supera il numero massimo di caratteri (di x)
ticket_id id No Associerà la sessione a un ID ticket CRM specifico Nota: gli ID ticket non validi verranno ignorati.

Errore e successo

Richiesta Risultato atteso Copia
Il servizio SMS è attivato
Il servizio SMS in uscita è attivato
Il valore di chat_type è "OutboundSMSAPI"
end_user_number è fornito e ben formato
outbound_number è fornito e ben formato
Per i numeri di telefono non statunitensi: il numero di telefono non statunitense è attivato
Il messaggio è fornito
Nessuna chat attiva tra outbound_number e end_user_number		 operazione riuscita (200) Esempio di risposta di successo
{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.000Z",
   "queued_at": null,
   "assigned_at": null,
   "ends_at": null,   "wait_duration": 0,
   "chat_duration": 0,   "rating": null,
   "has_feedback": false, 
   "out_ticket_id": null,
   "out_ticket_url": null,
   "verified": false,
   "disconnected_by": "disconnected_by_unknown",
   "fail_reason": null,
   "selected_menu": null,
   "menu_path": null,
   "agent_info": null,
   "end_user": {       "id": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}
Vengono forniti l'ID agente e l'email dell'agente errore È possibile fornire solo uno dei due valori: agent_id o agent_email.
L'ID agente o l'email dell'agente è fornito
L'agente non è connesso alla chat esistente		 errore SMS in uscita non riuscito. L'agente non è connesso alla chat.
Il servizio SMS non è attivo errore "Il servizio SMS non è attivo".
Il servizio SMS in uscita non è attivo errore "Il servizio SMS in uscita non è attivo"
chat_type non è fornito errore "chat_type needs to be provided" (è necessario fornire chat_type)
chat_type è fornito, ma non è impostato su "sms" errore "È necessario fornire un valore chat_type valido"
end_user_number è fornito, ma non è ben formato errore "end_user_number is invalid"
(nota: numero di telefono valido: "+18882468888" per un numero di telefono statunitense)
end_user_number non è fornito errore "end_user_number is required"
outbound_number è fornito, ma non è ben formato errore "outbound_number is invalid"
(nota: numero di telefono valido: "+18882468888" per un numero di telefono statunitense)
outbound_number viene fornito, ma non esiste per quel tenant errore "outbound_number is not found"
outbound_number non è fornito errore "outbound_number is required"
outbound_number è un numero di telefono non statunitense e "non US phone number service" non è abilitato errore "Il servizio di numeri di telefono non statunitensi non è attivato"
Nota: dipende dall'impostazione Numero di telefono non statunitense in Impostazioni > SMS durante la chiamata > Configurazioni numero di telefono non statunitense
Il messaggio è vuoto errore "message is required" (il messaggio è obbligatorio)
Chat attiva tra outbound_ number e end_user_number errore "SMS in uscita non riuscito. Il consumatore è già in una sessione SMS attiva."
ticket_id è compilato, ma non esiste nel CRM errore "Biglietto non trovato"

Scadenza SMS

I messaggi SMS in uscita sono attivi non appena vengono inviati.

Qualsiasi chat SMS deve terminare prima che possa essere stabilita una nuova sessione di chat SMS tra un determinato numero di telefono in uscita e un numero di telefono del consumatore. Ciò include i messaggi SMS in uscita inviati utilizzando l'API. Qualsiasi SMS in uscita non andrà a buon fine se esiste una chat attiva tra i numeri di telefono in uscita e del consumatore.

Opzioni di timeout automatico della chat

Le opzioni di timeout automatico della chat sono configurate in Impostazioni > Chat > Scadenza SMS e timeout globale. Fornisce controlli per la durata di una sessione di chat se non si verificano attività o progressi nel flusso della sessione di chat.

Distinzioni tra gli stati della chat

Di seguito sono riportate le distinzioni tra le modifiche dello stato del processo di chat:

  • Stato di selezione della coda Scadenza chatLe chat in uscita inviate tramite l'API vengono considerate nello stato di selezione della coda finché il consumatore non risponde

    Qualsiasi sessione di chat che non sia andata oltre lo stato di selezione della coda. Sono inclusi i messaggi SMS in uscita inviati a un consumatore a cui non ha risposto. È possibile definire per quanto tempo una chat può rimanere in questo stato prima della scadenza (messaggio inviato e consumatore non risponde entro il timer - la chat scade).

  • Scadenza della chat SMS senza risposta (durante l'orario di servizio)Il periodo di tempo in cui una chat può rimanere senza risposta in una coda prima di scadere entro l'orario di servizio impostato per la coda specifica.

  • Scadenza della chat SMS senza risposta (durante l'orario non lavorativo)Il periodo di tempo in cui una chat può rimanere senza risposta in una coda prima della scadenza al di fuori dell'orario di attività impostato per la coda specifica.

  • Timeout chat SMS in uscita Le sessioni di chat SMS in uscita scadranno automaticamente se non viene rilevata attività per [x] minuti.

Dettagli sullo stato della chat

  • Quando viene inviato un SMS in uscita utilizzando l'API, la chat è considerata attiva ma non connessa

  • Queste chat SMS in uscita attive sono considerate in stato di selezione della coda finché il consumatore non risponde

  • Le chat vengono considerate connesse quando il consumatore risponde e viene assegnato un agente alla chat

Impatto dello stato della chat sui timer applicati

  • Le chat attive inviate utilizzando l'API che non hanno ricevuto una risposta dal consumatore sono soggette al timer dello stato di selezione della coda

  • Le chat collegate a un agente sono soggette al timer di scadenza in uscita

  • Se un consumatore risponde al messaggio iniziale, ma non viene mai assegnato un agente, la chat non viene collegata ed è soggetta al timer di scadenza della chat senza risposta, durante o dopo l'orario di apertura

Esempio di flusso e stati dei messaggi API:

  1. Il messaggio SMS viene inviato tramite l'API al consumatore. La chat è in stato di selezione della coda e non è connessa a un agente

  2. Viene avviato il timer di scadenza della chat di selezione della coda. La chat scade e termina se il consumatore non risponde entro la soglia del timer.

  3. Risposte del consumatore alla chat: la chat è ora collegata a un agente.

  4. Il consumatore invia l'ultimo messaggio. Si avvia il timer di timeout della chat SMS in uscita.

  5. È stata raggiunta la soglia del timer di timeout della chat SMS in uscita. La chat è terminata.

Nessun timer di chiusura della chat: per le sessioni SMS in uscita avviate tramite API, il timer di chiusura della chat non funziona, quindi non si verifica un evento di chiusura della chat anche dopo che la chat viene visualizzata come chat in entrata quando un consumatore risponde al messaggio.

Definizione della risposta

L'API risponde con un singolo oggetto chiamata, come mostrato nel modello di /calls.

API SMS in uscita senza sessione

La piattaforma CCAI offre un'API SMS in uscita che può supportare messaggi SMS in uscita senza sessioni collegate.

Questa chiamata API avvia messaggi SMS non collegati alla sessione che possono essere attivati durante un flusso di lavoro esistente utilizzando CCAI Platform.

Un SMS senza sessione è preferibile nei casi in cui viene inviato un solo messaggio ai consumatori e non è necessario aprire un ticket CRM.

Questa API SMS in uscita consente di inviare fino a 500 messaggi per chiamata API.

Casi d'uso

I casi d'uso comuni per un SMS senza sessione possono includere:

  • Configurazione della password monouso.

  • Codice di verifica.

  • Promemoria per appuntamenti.

  • Link del feedback.

  • Messaggi di marketing o promozionali.

L'API in uscita senza sessione e l'API SMS in uscita differiscono in quanto con l'API SMS in uscita, quando un consumatore risponde, viene avviata una sessione attiva e può essere indirizzato a un agente. Sebbene condividano casi d'uso simili (notifiche di consegna, promemoria di appuntamenti), la differenza sta in cosa succede quando il consumatore risponde. Potrebbero ricevere una notifica predefinita di non risposta senza sessione, ma con gli SMS in uscita verranno indirizzati a un agente.

Endpoint API SMS in uscita senza sessione

L'URI di base per questo endpoint è:

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

Aggiungere una credenziale API

  1. Nel portale della piattaforma CCAI, vai a Impostazioni > Impostazioni sviluppatore > Gestione credenziali API.

  2. Fai clic sul pulsante + Aggiungi credenziale API. Viene visualizzato un messaggio Aggiungi credenziale API.

  3. Inserisci un nome per la credenziale Nome.

  4. Fai clic su Crea.

Invio di messaggi SMS

Per inviare un SMS in uscita senza sessione, chiama POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms e trasmetti i seguenti parametri della richiesta:

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}
Nome campo Tipo Obbligatorio Descrizione Note
from_phone Stringa Sì Il numero di telefono da cui verranno inviati i messaggi. Deve essere un numero statunitense valido.
La chiamata API restituirà un errore se:
* il numero di telefono non è un numero di telefono per SMS associato al tenant
* il campo from_phone è vuoto
* il numero di telefono non segue il formato corretto. Ad esempio, il seguente numero è un numero di telefono statunitense valido: +18882468888
to_phones Array [Stringa] Sì I numeri di telefono a cui verranno inviati i messaggi. Per garantire la riuscita della chiamata API:
* Verifica di avere un numero di telefono valido, ad esempio +18882468888
Il numero massimo di numeri di telefono è 100 per chiamata API.
messaggi Array [Stringa] Sì I messaggi da inviare. Il numero massimo di messaggi separati che puoi inviare è 5.
Ogni messaggio ha un limite di 320 caratteri e non può superarlo.

Risposte API

Se la chiamata API va a buon fine, vedrai:

  • code: 200

  • ID richiesta

    Assicurati di registrare l'ID richiesta nei record di sistema. Se devi risolvere un problema, l'assistenza avrà bisogno dell'ID richiesta per aiutarti.

Se la chiamata API non va a buon fine, vedrai:

  • code: 4xx

  • Messaggio di errore

Limitazioni per gli SMS

  • L'API elabora un massimo di 300 messaggi al minuto.

  • Tutti i messaggi non elaborati scadranno tra 2 ore.