La richiesta esterna ti consente di integrare il tuo bot con qualsiasi sistema dotato di API. Puoi utilizzare le richieste esterne per ottenere dati da qualsiasi altro sistema e visualizzare i dati all'utente all'interno del tuo Chatbot.
Come utilizzare la richiesta esterna?
Nel generatore di flusso, aggiungereActions>Richiesta API esterna.
Come salvare i dati in un campo personalizzato?
È possibile utilizzareMapping rispostaper salvare i dati dall'API a unPersonalizzato CampoSe l'API restituisce dati in formato JSON. Molte volte potresti voler ottenere dati da un'API e mostrarli all'utente.
Ad esempio, utilizzeremo un'API di cambio valuta per mostrare come salvare i dati restituiti da un'API in un campo personalizzato. Di seguito è riportata la risposta dall'API.
{
"success": true,
"timestamp": 1519296206,
"base": "EUR",
"date": "2021-03-17",
"rates": {
"AUD": 1.566015,
"CAD": 1.560132,
"CHF": 1.154727,
"CNY": 7.827874,
"GBP": 0.882047,
"JPY": 132.360679,
"USD": 1.23396
}
}Se vogliamo mostrare il valore in USD, dovrai utilizzarerates.USD, ti consigliamo di testare la tua richiesta, copiare la risposta e utilizzare questoserviceper ottenere il JSONPath corretto. Inoltre, puoi utilizzare questo servizio per verificare se il tuo JSONPath è corretto. Non è necessario avviare JSONPath conx.
Esistono due modi per visualizzare i dati restituiti da un'API all'utente all'interno del bot. Puoi salvare i dati in un campo personalizzato utilizzando la mappatura delle risposte e utilizzare il campo personalizzato nel flusso per mostrare i dati all'utente. Inoltre, la tua API potrebbe restituire messaggi pronti per essere visualizzati all'utente finale all'interno del tuo bot (Dynamic Contents). I contenuti dinamici sono spiegati di seguito in questo articolo.
Come ottenere il codice di stato HTTP o l'intero corpo della risposta?
Nella mappatura della risposta, utilizzarehttp_status_codeper ottenere il codice di risposta e utilizzarehttp_response_bodyper ottenere l'intero corpo della risposta. Dopo aver salvato il codice di stato HTTP in un campo personalizzato, puoi utilizzare le condizioni per eseguire qualsiasi logica desideri. Per scaricare un file, utilizzarehttp_download_EXTENSION.Ad esempio, per scaricare l'audio, potresti utilizzarehttp_download_mp3.
Dynamic Content
I contenuti dinamici ti consentono di generare contenuti dal tuo server e mostrarli all'utente all'interno del tuo Chatbot. Il contenuto dinamico è supportato su tutti i canali. Utilizzi un unico formato che funziona su tutti i canali. La nostra piattaforma converte automaticamente il tuo messaggio in tempo reale e lo consegna all'utente.
Non puoi utilizzare la funzione Contenuto dinamico se non possiedi l'API da cui ricevi i dati. In questo caso, puoi salvare i dati dall'API in un campo personalizzato utilizzandoMapping rispostae visualizzare i dati utilizzando il campo personalizzato nel generatore di flusso.
Il formato della risposta è riportato di seguito.
{
"messages": [],
"actions": []
}Messaggi: contiene i messaggi inviati ai contatti. Puoi inviare qualsiasi messaggio supportato da Messenger Bots. Questo articolo mostra alcuni esempi di formato, ma puoi leggere ladocumentazione di Facebookse hai bisogno di più funzionalità.
Pengo Bot invia un'intestazione "X-USER-ID" su ogni richiesta.
quick_repliesè sempre facoltativo.
Invia un messaggio di testo.
{
"messages": [
{
"message": {
"text": "Hello world",
"quick_replies":[]
}
}
]
}
Invio di più di un singolo messaggio
{
"messages": [
{
"message": {
"text": "Hello world"
}
},
{
"message": {
"text": "This is the second Message",
"quick_replies":[]
}
}
]
}Invio di un messaggio di testo con pulsanti.
Il messaggio di testo può contenere fino a 3 pulsanti. Il titolo di ciascun pulsante può contenere fino a 20 caratteri. Per inviare un flusso quando un utente fa clic su un pulsante, utilizza un ID flusso come payload del pulsante.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"buttons": [
{
"title": "Open Website",
"type": "web_url",
"url": "your_URL"
},
{
"title": "Send FLow",
"payload": "FLOW_OR_STEP_ID",
"type": "postback"
},
{
"title": "Call Number",
"type": "phone_number",
"payload": "<your_phone_number_with_county_code>"
}
],
"template_type": "button",
"text": "Hello world"
},
"type": "template"
},
"quick_replies":[]
}
}
]
}Payload: puoi utilizzare qualsiasiflow/step IDcome carico utile. Ad esempio, se desideri reindirizzare a un flusso una volta che l'utente fa clic sul pulsante, puoi utilizzare l'ID flusso come payload. In questo articolo, mostriamo come utilizzareactionsanche come payload.
Invio di un messaggio con risposte rapide
Le risposte rapide possono essere aggiunte a qualsiasi tipo di messaggio (testo, file, galleria, file, ...). Facebook ti consente di allegare un massimo di 11 risposte rapide a un messaggio. Il payload per le risposte rapide è lo stesso del payload per i pulsanti.
{
"messages": [
{
"message": {
"text": "Hello world",
"quick_replies":[
{
"content_type": "text",
"title": "Quick Reply 1",
"payload": "FLOW_OR_STEP_ID"
},
{
"content_type": "text",
"title": "Any Text Here",
"payload": "FLOW_OR_STEP_ID"
}
]
}
}
]
}I payload sulle risposte rapide e sui pulsanti hanno la stessa struttura.
Invia un'immagine, un video, un audio, un file.
Puoi utilizzare la stessa struttura di seguito per inviare un'immagine, un video, un audio e un file. Basta cambiare media_type in video, audio o file. "URL" sarà il collegamento alla tua immagine, audio, video o file.
{
"messages": [
{
"message": {
"attachment": {
"type": "image",
"payload": {
"url": "<ASSET_URL>"
}
},
"quick_replies":[]
}
}
]
}Invia una singola scheda
Il titolo e il sottotitolo della scheda possono contenere fino a 80 caratteri.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"elements": [
{
"title": "Card Title",
"subtitle": "Card Subtitle",
"image_url": "image_url"
}
],
"template_type": "generic",
"image_aspect_ratio":"horizontal"
},
"type": "template"
},
"quick_replies":[]
}
}
]
}Valori possibili per rapporto_aspetto_immagine: orizzontale o quadrato
Invia una singola scheda con pulsanti
Una scheda può contenere fino a 3 pulsanti.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"elements": [
{
"title": "Card Title",
"subtitle": "Card Subtitle",
"image_url": "image_url",
"buttons": [
{
"title": "Button Label",
"type": "web_url",
"url": "your_URL"
},
{
"title": "Button Label",
"payload": "FLOW_OR_STEP_ID",
"type": "postback"
},
{
"title": "Button Label",
"type": "phone_number",
"payload": "+your_phone_number"
}
]
}
],
"template_type": "generic",
"image_aspect_ratio":"horizontal"
},
"type": "template"
},
"quick_replies":[]
}
}
]
}Invia una Galleria
Fondamentalmente, una galleria è un insieme di carte. Una galleria può contenere fino a 10 carte. Il codice seguente mostra una galleria con 2 carte. Puoi anche aggiungere un pulsante a ciascuna scheda.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"elements": [
{
"title": "Card Title 1",
"subtitle": "Card Subtitle 1",
"image_url": "image_url 1",
"buttons": []
},
{
"title": "Card Title 2",
"subtitle": "Card Subtitle 2",
"image_url": "image_url 2",
"buttons": []
}
],
"template_type": "generic",
"image_aspect_ratio":"horizontal"
},
"type": "template"
},
"quick_replies":[]
}
}
]
}Invia messaggi supportati solo da WhatsApp
WhatsApp supporta molti tipi di messaggi che non sono supportati dai bot di Messenger come Elenco, Contatti, Posizioni o Messaggi di cataloghi. Pengo Bot ti consente di inviare qualsiasi messaggio supportato da WhatsApp. Devi solo fornire la stessa struttura del messaggio descritta nella documentazione diWhatsApp. Pengo Bot imposterà automaticamente il parametro "To".
{
"messages":[
{
"messaging_product":"whatsapp",
"recipient_type": "individual",
"to": null,
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "ANY TEXT"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "FLOW_OR_STEP_ID",
"title": "BUTTON_TITLE_1"
}
},
{
"type": "reply",
"reply": {
"id": "FLOW_OR_STEP_ID",
"title": "BUTTON_TITLE_2"
}
}
]
}
}
}
]
}Esegui azioni durante l'invio di messaggi
La tua risposta API può istruire il nostro sistema a eseguire automaticamente le azioni.
Aggiungi tag
{
"messages": [],
"actions": [
{
"action": "add_tag",
"tag_name": "..."
}
]
}Rimuovi tag
{
"messages": [],
"actions": [
{
"action": "remove_tag",
"tag_name": "..."
}
]
}Imposta campo personalizzato
Oltre ad accettare qualsiasi nome di campo personalizzato, questa azione consente anche di modificare il sistema campi comephone,email, full_name, first_name, last_name
{
"messages": [],
"actions": [
{
"action": "set_field_value",
"field_name": "...",
"value": ""
}
]
}Unset Custom Field
{
"messages": [],
"actions": [
{
"action": "unset_field_value",
"field_name": "..."
}
]
}Send Flow
Per ottenere l'ID del flusso, devi andare all'elenco dei flussi, fare clic sui 3 punti e fare clic suOttieni collegamento. Il flow-id è il numero incluso nel tuo collegamento. L'ID del flusso è sempre numerico. Puoi combinare un numero illimitato di azioni.
{
"messages": [],
"actions": [
{
"action": "send_flow",
"flow_id": "..."
}
]
}Trasferisci conversazione a umano/bot
{
"messages": [],
"actions": [
{
"action": "transfer_conversation_to",
"value": "human"
}
]
}Assegna una conversazione a admin
{
"messages": [],
"actions": [
{
"action": "assign_conversation",
"admin_id": "..."
}
]
}Annulla assegnazione di conversazione da admin
{
"messages": [],
"actions": [
{
"action": "unassign_conversation"
}
]
}Combina più azioni
Puoi combinare più azioni in un'unica richiesta per consentirti di eseguirne più contemporaneamente. Ad esempio, potresti voler impostare un campo personalizzato e inviare un flusso in una singola richiesta.
{
"messages": [],
"actions": [
{
"action": "set_field_value",
"field_name": "...",
"value": ""
},
{
"action": "send_flow",
"flow_id": "..."
}
]
}Utilizza azioni come carico utile di pulsanti e risposte_rapide
Di seguito è il formato per utilizzare un'azione come carico utile sui pulsanti. Ma poiché un payload è una stringa, devi convertire l'oggetto actions in una stringa JSON. Se utilizzi PHP, utilizza json_encode per ottenere una rappresentazione di stringa del tuo oggetto.
{
"actions": [
{
"action": "send_flow",
"flow_id": "..."
}
]
}Di seguito, l'azione sopra viene utilizzata come carico utile del pulsante.
{
"messages": [
{
"message": {
"attachment": {
"payload": {
"buttons": [
{
"title": "Click Here",
"payload": "{\"actions\":[{\"action\":\"send_flow\",\"flow_id\":\"FLOW_OR_STEP_ID\" } ]}",
"type": "postback"
}
],
"template_type": "button",
"text": "Hello world"
},
"type": "template"
},
"quick_replies":[]
}
}
]
}Limitations
1 – Il limite di velocità API predefinito è 100 richieste per 60 secondi per account bot.