Trigger a Twilio Studio Flow Execution via the REST API

To trigger a Studio Flow via the REST API, your application needs to make an HTTP POST request to the Flow's Resource. There are three required pieces of information for your request; The flow's SID, the recipient and the sender.

Important: In order to successfully execute flows via the REST API, your flow's Trigger widget must have a transition from the REST API lead to a valid widget.
Studio_api.png

API Request Example

Here’s an example cURL script:

curl -X POST https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will contact the destination (310) 555-5555 from the sender (212) 555-1234, and execute the REST API trigger on flow FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. To make this script work for you, make the following updates, and then paste it into a terminal window:

  • Line 1 update with a valid Flow SID
  • Line 2 update with a valid destination
  • Line 3 update with a valid sender number
  • Line 4 update with your Account SID and Auth Token.

Custom Parameters

The Studio API also accepts custom parameters in your request that are visible to your widgets as variables. These parameters need to be included in your API request as JSON values in the form of Parameters={"parameter_name":"value"}. When a request is received with custom parameters, they can be accessed in your widget with via a variable. This is helpful when using Studio for contact templates, passing custom parameters for someone's name, dates, times, amount due, and more. 

Here’s an example cURL script:

curl -X POST https://studio.twilio.com/v1/Flows/FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Executions \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
--data-urlencode "Parameters={\"patient\":\"Jon\",\"time\":\"8AM\"}" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will contact the destination (310) 555-5555 from the sender (212) 555-1234, and execute the REST API trigger on flow FWXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. In this execution, the parameters patient:Jon and time:8AM will also be passed to your flow. To make this script work for you, make the following updates, and then paste it into a terminal window:

  • Line 1 update with a valid Flow SID
  • Line 2 update with a valid destination
  • Line 3 update with a valid sender number
  • Line 4 update with the desired parameters
  • Line 5 update with your Account SID and Auth Token.

In your flow, the passed parameters will be available via a variable in the form of {{flow.data.parameter_name}}. Any time we see this, we'll automatically replace it with the parameter's value.

For example, if we were to send the above API request to a flow with a Send Message widget with the following Message Body:

Reminder from the Doctor's office: Patient {{flow.data.patient}} has an appointment tomorrow at {{flow.data.time}}.

The recipient would receive the following message:

Reminder from the Doctor's office: Patient Jon has an appointment tomorrow at 8AM.

Additional Resources

For full details, please see our Twilio Studio REST API documentation.

Have more questions? Submit a request
Powered by Zendesk