Come utilizzare le richieste esterne e i contenuti dinamici?

La funzionalità Richiesta esterna consente di integrare il tuo bot con qualsiasi sistema dotato di un'API. Puoi usare le richieste esterne per recuperare dati da qualsiasi altro sistema e mostrarli all'utente all'interno del tuo chatbot.

Come usare una richiesta esterna?

Nell'editor dei flussi, aggiungi Azioni > Richiesta API esterna.

Come salvare i dati in un campo personalizzato?

Puoi usare la Mappatura della risposta per salvare i dati di un'API in un Campo personalizzato, se l'API restituisce i dati in formato JSON. Spesso potresti voler recuperare dati da un'API e mostrarli all'utente.

Per esempio, useremo un'API per i tassi di cambio per mostrare come salvare i dati restituiti da un'API in un campo personalizzato. Di seguito è riportata la risposta dell'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 vuoi mostrare il valore in USD, dovrai usare rates.USD. Ti consigliamo di testare la richiesta, copiare la risposta e usare questo servizio per ottenere il JSONPath corretto. Puoi usare questo servizio anche per verificare che il tuo JSONPath sia corretto. Non è necessario iniziare il JSONPath con x.

Esistono due modi per mostrare all'utente i dati restituiti da un'API all'interno del tuo bot. Puoi salvare i dati in un campo personalizzato usando la Mappatura della risposta e usare il Campo personalizzato nel flusso per mostrare i dati all'utente. In alternativa, la tua API può restituire messaggi pronti per essere mostrati all'utente finale all'interno del bot (Contenuti dinamici). I contenuti dinamici sono spiegati più avanti in questo articolo.

Come ottenere il codice di stato HTTP o l'intero corpo della risposta?

Nella mappatura della risposta, usa http_status_code per ottenere il codice di stato della risposta e http_response_body per ottenere l'intero corpo della risposta. Dopo aver salvato il codice di stato HTTP in un campo personalizzato, puoi usare le condizioni per applicare la logica che desideri. Per scaricare un file, usa http_download_EXTENSION. Per esempio, per scaricare un file audio, puoi usare http_download_mp3.

Contenuti dinamici

I contenuti dinamici consentono di generare contenuti dal tuo server e mostrarli all'utente all'interno del tuo chatbot. I contenuti dinamici sono supportati su tutti i canali. Puoi usare un unico formato che funziona su tutti i canali. La nostra piattaforma converte automaticamente il tuo messaggio in tempo reale e lo invia all'utente.

Non puoi usare la funzionalità Contenuti dinamici se non sei il proprietario dell'API da cui recuperi i dati. In questo caso, puoi salvare i dati dell'API in un Campo personalizzato usando la Mappatura della risposta e mostrarli usando il Campo personalizzato nell'editor dei flussi.

Il formato della risposta è riportato di seguito.

{
    "messages": [],
    "actions": []
}

Messages: contiene i messaggi inviati ai contatti. Puoi inviare qualsiasi messaggio supportato dai bot di Messenger. Questo articolo mostra alcuni esempi di formato, ma puoi consultare la documentazione di Facebook se hai bisogno di ulteriori funzionalità.

Pengo invia l'intestazione ‘ X-USER-ID‘ con ogni richiesta.

quick_replies è sempre facoltativo.

Inviare un messaggio di testo.

{
    "messages": [
        {           
            "message": {
                "text": "Hello world",
                "quick_replies":[]
            }
            
        }
    ]
}

Inviare più di un messaggio

{
    "messages": [
        {
            "message": {
                "text": "Hello world"
            }
        },
        {
            "message": {
                "text": "This is the second Message",
                "quick_replies":[]
            }
        }
    ]
}

Inviare 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, usa l'ID di un 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 usare qualsiasi ID di flusso/passaggio come payload. Per esempio, se vuoi reindirizzare a un flusso quando l'utente fa clic sul pulsante, puoi usare l'ID del flusso come payload. In questo articolo mostriamo anche come usare actions come payload.

Inviare un messaggio con risposte rapide

Le risposte rapide possono essere aggiunte a qualsiasi tipo di messaggio (testo, file, galleria, file, …). Facebook consente di aggiungere a un messaggio un massimo di 11 risposte rapide. Il payload delle risposte rapide è lo stesso dei 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 delle risposte rapide e dei pulsanti hanno la stessa struttura.

Inviare un'immagine, un video, un audio o un file.
Puoi usare la stessa struttura riportata di seguito per inviare un'immagine, un video, un audio o un file. Basta modificare media_type in video, audio o file. “URL” sarà il link alla tua immagine, al tuo audio, al tuo video o al tuo file.

{
    "messages": [
        {
            "message": {
                "attachment": {
                    "type": "image",
                    "payload": {
                        "url": "<ASSET_URL>"
                    }
                },
                "quick_replies":[]
            }
        }
    ]
}

Inviare una singola scheda
Il titolo e il sottotitolo della scheda possono contenere fino a 80 caratteri ciascuno.

{
    "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 image_aspect_ratio: horizontal o square

Inviare 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":[]
            }
        }
    ]
}

Inviare una galleria
Una galleria è, in sostanza, un insieme di schede. Una galleria può contenere fino a 10 schede. Il codice seguente mostra una galleria con 2 schede. 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":[]
            }
        }
    ]
}

Inviare messaggi supportati solo da WhatsApp

WhatsApp supporta molti tipi di messaggi che non sono supportati dai bot di Messenger, come messaggi con elenchi, contatti, posizioni o cataloghi. Pengo consente di inviare qualsiasi messaggio supportato da WhatsApp. Devi solo fornire la stessa struttura del messaggio descritta nella documentazione di WhatsApp. Pengo 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"
                        }
                    }
                ]
                }
            }
        }
    ]
}

Eseguire azioni durante l'invio dei messaggi

La risposta della tua API può indicare al nostro sistema di eseguire automaticamente delle azioni.

Aggiungere un tag

{
    "messages": [],
    "actions": [
        {
            "action": "add_tag",
            "tag_name": "..."
        }
    ]
}

Rimuovere un tag

{
    "messages": [],
    "actions": [
        {
            "action": "remove_tag",
            "tag_name": "..."
        }
    ]
}

Impostare un campo personalizzato

Oltre ad accettare qualsiasi nome di campo personalizzato, questa azione consente anche di modificare campi di sistema come phone, email, full_name, first_name, last_name

{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "...",
            "value": ""
        }
    ]
}

Svuotare un campo personalizzato

{
    "messages": [],
    "actions": [
        {
            "action": "unset_field_value",
            "field_name": "..."
        }
    ]
}

Inviare un flusso
Per ottenere l'ID del flusso, vai all'elenco dei flussi, fai clic sui 3 puntini e poi su Ottieni link. L'ID del flusso è il numero incluso nel link. L'ID del flusso è sempre numerico. Puoi combinare un numero illimitato di azioni.

{
    "messages": [],
    "actions": [
        {
            "action": "send_flow",
            "flow_id": "..."
        }
    ]
}

Trasferire la conversazione a un operatore umano o a un bot

{
    "messages": [],
    "actions": [
        {
            "action": "transfer_conversation_to",
            "value": "human"
        }
    ]
}

Assegnare una conversazione a un amministratore

{
    "messages": [],
    "actions": [
        {
            "action": "assign_conversation",
            "admin_id": "..."
        }
    ]
}

Rimuovere l'assegnazione di una conversazione a un amministratore

{
    "messages": [],
    "actions": [
        {
            "action": "unassign_conversation"
        }
    ]
}

Combinare più azioni

Puoi combinare più azioni in un'unica richiesta per eseguirle contemporaneamente. Per esempio, potresti voler impostare un campo personalizzato e inviare un flusso con un'unica richiesta.

{
    "messages": [],
    "actions": [
        {
            "action": "set_field_value",
            "field_name": "...",
            "value": ""
        },
        {
            "action": "send_flow",
            "flow_id": "..."
        }
    ]
}

Usare le azioni come payload di pulsanti e quick_replies

Di seguito è riportato il formato da usare per inserire un'azione come payload dei pulsanti. Tuttavia, poiché un payload è una stringa, devi convertire l'oggetto delle azioni in una stringa JSON. Se usi PHP, usa json_encode per ottenere una rappresentazione del tuo oggetto sotto forma di stringa.

{   
    "actions": [
        {
            "action": "send_flow",
            "flow_id": "..."
        }
    ]
}

Di seguito, l'azione precedente viene usata come payload 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":[]
            }            
        }
    ]
}

Limitazioni

1 – Il limite predefinito di frequenza delle richieste API è di 100 richieste ogni 60 secondi per account bot.