Start Conversations via API

This guide will walk you through the usage of Truora’s API for sending an approved Outbound Message that triggers a WhatsApp Flow to guide the conversation upon customer acceptance.

To get started, ensure the following prerequisites are met before proceeding with the API steps.

Prerequisites

Truora Account: If you don’t already have one, learn how to Set up a Truora account.
Truora API-Key: This key grants access to our services. If you don’t have one already go to Create Truora API-Key.
Activated Whatsapp line: Follow this guide to acquire and activate WhatsApp lines in Truora.
A Created Whatsapp Flow: Have at least one flow already built. Learn how to Create a WhatsApp Flow in Truora.
Created and Approved Outbound Message: Ensure you have created an Outbound Message with conversation type set to Flow, and that it is approved in compliance with META’s guidelines. This message will be used to initiate first contact with customers or to recontact them. Refer to the Outbound Message Guide for more information.

Once the prerequisites are in place, you’ll need:

Flow ID: ID of the flow you want to trigger.
Outbound ID: ID of the Outbound Message that your user will receive before triggering the Flow.

The Outbound Message is what will be sent to your users, and it’s linked to the specified flow to guide the conversation.

Getting the Flow ID via Dashboard

In the Dashboard, click Open under WhatsApp Customer Engagement.
Navigate to My flows and click the copy icon next to the Flow ID of the desired flow.

Getting the Outbound ID via Dashboard

In the Dashboard sidebar, click Outbound Messages.
Find the desired Outbound name in the list and click the copy icon below it to copy the Outbound ID.

Getting the Outbound ID via API

As an alternative to retrieving the Outbound ID through the Dashboard, you can use the List Outbounds API request to obtain all Outbound Messages linked to your WABA line. The API response will provide details on each message, including its status and ID, helping you quickly identify the Outbound Message you want to use.

To make the List Outbounds request:

Set the Headers
- Truora-API-Key: Enter your Truora API Key.
Create a GET request to the endpoint https://api.connect.truora.com/v1/whatsapp/outbounds with the following Query Parameter:
- line [Required]: The WABA phone number to list outbounds from, including the country code without the ‘+’ sign.

Send the request. The response should look something similar to the following:

GET
/v1/whatsapp/outbounds?line=194XXXXXXXX


    [
        {
            "client_id": "TCI67c005XXXXXXXXXXXXXXXXX",
            "outbound_id": "OTB29XXXXXXXXXXXXXXXX",
            "outbound_name": "Demo template EN",
            "outbound_status": "APPROVED",
            "failure_reason": "",
            "is_notification": false,
            "outbound_message": "Hi! this is a TruConnect test. Select “Continue” and try your first flow. | [Continue] | [Cancel]",
            "outbound_answers": [
                {
                    "message": "Continue",
                    "action": "continue_process"
                },
                {
                    "message": "Cancel",
                    "action": "cancel_process"
                }
            ],
            "waba_phone_number": "+194XXXXXXXX",
            "media_url": "undefined",
            "outbound_type": "text",
            "media_id": ""
        },
        {
            "client_id": "TCI67c005XXXXXXXXXXXXXXXXX",
            "outbound_id": "OTBe38eXXXXXXXXXXXXXXXXXXXX",
            "outbound_name": "Demo Template PT",
            "outbound_status": "APPROVED",
            "failure_reason": "",
            "is_notification": false,
            "outbound_message": "Ola! este é um teste de TruConnect. Selecione “Continuar” e tente seu primeiro fluxo. | [Continuar] | [Cancelar]",
            "outbound_answers": [
                {
                    "message": "Continuar",
                    "action": "continue_process"
                },
                {
                    "message": "Cancelar",
                    "action": "cancel_process"
                }
            ],
            "waba_phone_number": "+194XXXXXXXX",
            "outbound_type": "text",
            "media_id": ""
        },
        {
            "client_id": "TCI67c005XXXXXXXXXXXXXXXXX",
            "outbound_id": "OTBbc9XXXXXXXXXXXXXXXXXXXX",
            "default_flow_id": "IPFe6dccbc22634b9934cbbb1696bd5ca04",
            "outbound_name": "Demo Template ES",
            "outbound_status": "APPROVED",
            "failure_reason": "",
            "is_notification": false,
            "outbound_message": "¡Hola! esta es una prueba de TruConnect. Seleccione “Continuar” y pruebe su primer flujo. | [Continuar] | [Cancelar]",
            "outbound_answers": [
                {
                    "message": "Continuar",
                    "action": "continue_process"
                },
                {
                    "message": "Cancelar",
                    "action": "cancel_process"
                }
            ],
            "waba_phone_number": "+194XXXXXXXX",
            "outbound_type": "text",
            "media_id": ""
        }
    ]

Locate the Outbound Message you want to use, and copy the outbound_id to include in subsequent requests. Additionally, you may confirm that the outbound_status is APPROVED before sending it to your users.

Checking your Outbound Message via API

This step is optional but can be useful in some cases. You can use the Get Outbound Message API request to review details about a specific Outbound Message by using its outbound_id. Among other information, the response will include:

is_notification: If false, indicates the Outbound Message is intended to initiate a Flow when the user accepts to continue.
outbound_message: Displays the content of your Outbound Message.
outbound_status: Indicates if the message is APPROVED by Meta and ready to use. Other statuses include PENDING and REJECTED.
waba_phone_number: The WABA line phone number associated with your Outbound Message.

To make the Get Outbound message request:

Set the Headers
- Truora-API-Key: Enter your Truora API Key.
Create a GET request to the endpoint https://api.connect.truora.com/v1/whatsapp/outbounds/{outbound_id}
- Replace the Path Parameter outbound_id with the ID of the Outbound Message you want to retrieve.

Send the request. The response should look something similar to the following:

GET
/v1/whatsapp/outbounds/{outbound_id}


    {
        "client_id": "TCI67c005XXXXXXXXXXXXXXXXX",
        "outbound_id": "OTB29XXXXXXXXXXXXXXXX",
        "outbound_name": "Demo template EN",
        "outbound_status": "APPROVED",
        "failure_reason": "",
        "is_notification": false,
        "outbound_message": "Hi! this is a TruConnect test. Select “Continue” and try your first flow. | [Continue] | [Cancel]",
        "outbound_answers": [
            {
                "message": "Continue",
                "action": "continue_process"
            },
            {
                "message": "Cancel",
                "action": "cancel_process"
            }
        ],
        "waba_phone_number": "+194XXXXXXXX",
        "media_url": "undefined",
        "outbound_type": "text",
        "media_id": ""
    }

Sending the message via API

Finally, use the flow_id and outbound_id from previous steps to send the Outbound Message to your users:

Create a POST request to the endpoint https://api.connect.truora.com/v1/whatsapp/outbounds/send
Set the Headers
- Truora-API-Key enter the value of your Truora API Key.
- Content-Type the value should be application/x-www-form-urlencoded.
Set required values for the request body
- phone_number [Required]: The recipient’s phone number without the country code.
- country_code [Required]: The country code for the phone number. Find a list of country codes here.
- outbound_id [Required]: The ID of your approved Outbound Message.
- user_authorized [Required]: Indicates that the recipient has authorized the communication (opt-in). Must be set to true.
- flow_id [Optional]: Required if is_notification field in the Outbound Message is set to false. This indicates that the Outbound Message will be used to initiate a Flow when the user accepts to continue. Provide the Flow ID of the specific Flow that will start upon user acceptance of the message.
- var.<variable_name> [Optional]: Required if the Outbound Message includes variables. You must provide a key-value pair for each variable in the message, formatted as var.<variable_name>. For example, if the message template is Hello {{.name}} {{.lastname}}, include var.name: John and var.lastname: Doe to display “Hello John Doe”.

Send the request. If everything is set correctly, you should receive a response similar to the following:

POST
/v1/whatsapp/outbounds/send


    {
        "user_phone_number": "+57314XXXXXXX",
        "message": "conversation started with +57314XXXXXXX",
        "session_id": "WDIS8ac148eXXXXXXXXXXXXXXXXXX",
        "outbound_message": {
            "client_id": "TCI67c005XXXXXXXXXXXXXXXXX",
            "outbound_id": "OTB29XXXXXXXXXXXXXXXX",
            "outbound_name": "Demo template EN",
            "outbound_status": "APPROVED",
            "failure_reason": "",
            "is_notification": false,
            "outbound_message": "Hi! this is a TruConnect test. Select “Continue” and try your first flow. | [Continue] | [Cancel]",
            "outbound_answers": [
                {
                    "message": "Continue",
                    "action": "continue_process"
                },
                {
                    "message": "Cancel",
                    "action": "cancel_process"
                }
            ],
            "waba_phone_number": "+19XXXXXXXX",
            "media_url": "undefined",
            "outbound_type": "text",
            "media_id": ""
        },
        "flow_id": "IPF1160XXXXXXXXXXXXXXXXXXXX"
    }

API Reference

For detailed information about our available API endpoints and requests, we encourage you to refer to our API reference.