Zapier Integration

Note:

The Sinch Conversation API integration for Zapier is currently in beta.

The Conversation API Zapier integration allows you to use features of the Conversation API with your Zapier solutions. There are a number of Conversation API triggers and actions you can include in your Zaps, which are automated workflows created using Zapier.

Note:

If you are unfamiliar with Zapier triggers, actions, and Zaps, see Zapier's Create your first Zap quick start guide.

Descriptions of the Sinch Conversation API actions and triggers, along with general prerequisite information, are below.

Prerequisites

In order to successfully integrate your Conversation API project and apps with your Zapier account, you must ensure that the following prerequisites are met.

Zapier prerequisites

Ensure that you have created a Zapier account.

Conversation API prerequisites

In order to successfully connect a Conversation API project to a Zapier account, and use Sinch actions and triggers with Zapier, you must have at least one Conversation API app with at least one configured channel. For information on how to create a Conversation API app and configure a channel on that app, see this Getting started guide.

Connect your Conversation API project

After you have met the above prerequisites, you are ready to connect your Conversation API account and project to your Zapier account.

In order for any Conversation API triggers or actions to function in your Zap, you must connect your Conversation API project to Zapier. In order to connect your Conversation API project to Zapier, you'll need to have the following pieces of information readily available:

  • Your access key ID
  • Your access key secret
  • Your project ID

To connect your account, simply begin configuring a Sinch trigger or action. If you have never connected a Sinch project to Zapier, you are prompted to do so. If you have already connected a Sinch project to Zapier, but would like to connect a new one, you can select + Connect a new account from the Sinch account drop-down list.

Zapier credentials

Enter the information and click Yes, Continue when you are done. Your Sinch project is now connected to Zapier! You will be able to select this project from the Sinch account drop-down list whenever you configure a Sinch Conversation API trigger or action.

Select your Conversation API app

Whenever you set up a Sinch Conversation API trigger or action, you must select the Conversation API app that will be used to recognize the trigger or complete the action. The available apps are based on which project you selected at the beginning of the trigger or action configuration process.

Triggers

There are a number of triggers, or events, that are defined for the Conversation API Zapier integration. These triggers can be used to initiate other Zapier actions. For the Conversation API integration, these Zapier triggers act as webhooks that can subscribe to Conversation API callback triggers.

Caution:

You can create, at most, five webhooks per Conversation API app. Each Conversation API Zapier trigger you create counts towards the maximum number of webhooks you can create per Conversation API app. If you attempt to associate a new Zapier trigger with a Conversation API app that already has five webhooks, a Webhook to delete drop-down list is displayed, allowing you select an existing webhook to replace.

After you configure a Conversation API trigger in Zapier, you'll gain access to the information provided by the Conversation API callback that is made when the corresponding callback trigger is activated.

New Inbound Message

This instant trigger is activated when an end-user sends a message to your Conversation API app. It corresponds to the MESSAGE_INBOUND callback trigger, and gathers information provided by the Inbound Message Conversation API callback. When this trigger is activated, the following fields are made available:

Field Description
Message Text The text included in the inbound message.
Message Accept time Timestamp marking when the channel callback was accepted/received by the Conversation API. Represented in ISO 8601 format.
Channel The Conversation API channel on which the message was sent.
User's Channel Identity (phone number, user ID etc) The identifier for the contact on the underlying channel. For example, the MSISDN corresponding to the contact if the message was sent on the SMS channel.
User's Sinch contact ID The contact ID belonging to the user that sent the message.
Conversation ID The ID of the conversation of which this message is a part.
Message Direction The direction of the message. Always set to TO_APP for contact messages.
Message ID The ID of the message.
Message Meta Data Any metadata associated with the corresponding conversation.
App ID The ID of the Conversation API app that received the message.
Accepted time Timestamp marking when the channel callback was accepted/received by the Conversation API. Represented in ISO 8601 format.
Event time Timestamp of the event as provided by the underlying channels. Represented in ISO 8601 format.
Project ID The ID of the project to which the app that received the message belongs.

User Opted In

This instant trigger is activated when Opt-in notifications or registration results are delivered. It corresponds to the OPT_IN callback trigger, and gathers information provided by the Opt In Conversation API callback. When this trigger is included in your Zap, the following fields are made available:

Field Description
App ID The ID of the Conversation API app that processed the notification or registration request.
Accepted time Timestamp marking when the channel callback was accepted/received by the Conversation API. Represented in ISO 8601 format.
Channel The Conversation API channel for which the notification or registration request was sent.
Contact ID The contact ID belonging to the user that is the subject of the Opt-in notification or registration.
User's Channel Identity (phone number, user ID etc) The channel identity corresponding to the contact that is the subject of the Opt-in notification or registration.
Request ID The unique ID of the request.
Opt-in status Indicates whether the Opt-in succeeded or failed.
Project ID The ID of the project that contains the App that processed the notification or registration request.

User Opted Out

This instant trigger is activated when Opt-out notifications or registration results are delivered. It corresponds to the OPT_OUT callback trigger, and gathers information provided by the Opt Out Conversation API callback. When this trigger is included in your Zap, the following fields are made available:

Field Description
App ID The ID of the Conversation API app that processed the notification or registration request.
Accepted time Timestamp marking when the channel callback was accepted/received by the Conversation API. Represented in ISO 8601 format.
Channel The Conversation API channel for which the notification or registration request was sent.
Contact ID The contact ID belonging to the user that is the subject of the Opt-out notification or registration.
User's Channel Identity (phone number, user ID etc) The channel identity corresponding to the contact that is the subject of the Opt-out notification or registration.
Request ID The unique ID of the request.
Opt-out status Indicates whether the Opt-out succeeded or failed.
Project ID The ID of the project that contains the App that processed the notification or registration request.

Other Callback Events

This instant trigger is activated when one or more Conversation API callback triggers are activated. You must select the Conversation API Callback Triggers that will activate this Zapier trigger. The choices in the Callback Triggers drop-down menu are:

  • Inbound Message, which corresponds to the MESSAGE_INBOUND callback trigger
  • Message Delivery, which corresponds to the MESSAGE_DELIVERY callback trigger
  • Inbound Event, which corresponds to the EVENT_INBOUND callback trigger
  • Event Delivery, which corresponds to the EVENT_DELIVERY callback trigger
  • Conversation Started, which corresponds to the CONVERSATION_START callback trigger
  • Conversation Ended, which corresponds to the CONVERSATION_STOP callback trigger
  • Contact Created, which corresponds to the CONTACT_CREATE callback trigger
  • Contact Deleted, which corresponds to the CONTACT_DELETE callback trigger
  • Contact Merged, which corresponds to the CONTACT_MERGE callback trigger
  • Capability Check Result, which corresponds to the CAPABILITY callback trigger
  • User Opted In, which corresponds to the OPT_IN callback trigger
  • User Opted Out, which corresponds to the OPT_OUT callback trigger
  • Other/Unsupported, which corresponds to the UNSUPPORTED callback trigger
Note:

For more information on Sinch callback triggers and payloads, click here.

When this trigger is added to your Zap, the fields that are made available depend on the Callback Triggers you selected. Depending on your selection, some or all of the following fields are made available when the trigger is included in your Zap:

Field Description
Message Accept time Timestamp marking when the channel callback was accepted/received by the Conversation API. Represented in ISO 8601 format.
Message Channel Identity Channel The channel on which the message was sent.
Message Channel Identity Identity The channel-specific identifier for the contact that sent the message.
Message Contact ID The contact ID of the user that sent the message.
Message Contact Message Text Message Text The text included in the inbound message.
Message Conversation ID The ID of the conversation of which the message is a part.
Message Direction The direction of the message. Always set to TO_APP for contact messages.
Message ID The unique ID of the message.
Message Meta Data Any metadata associated with the conversation.
App ID The ID of the Conversation API app that processed the callback.
Accepted time Timestamp marking when the channel callback was accepted/received by the Conversation API. Represented in ISO 8601 format.
Event time Timestamp of the event as provided by the underlying channels. Represented in ISO 8601 format.
Opt In Notification Channel The channel for which an Opt-in notification was received.
Opt In Notification Contact ID The contact ID belonging to the user that is the subject of the Opt-in notification or registration.
Opt In Notification Identity The channel-specific identifier for the contact that is the subject of the Opt-in notification or registration.
Opt In Notification Request ID The unique ID for a specific Opt-in request.
Opt In Notification Status Indicates whether the Opt-in succeeded or failed.
Opt Out Notification Channel TThe channel for which an Opt-out notification was received.
Opt Out Notification Contact ID The contact ID belonging to the user that is the subject of the Opt-out notification or registration.
Opt Out Notification Identity The channel-specific identifier for the contact that is the subject of the Opt-out notification or registration.
Opt Out Notification Request ID The unique ID for a specific Opt-out request.
Opt Out Notification Status Indicates whether the Opt-out succeeded or failed.
Project ID The ID of the project that contains the app that processed the callback.
Raw JSON response The full JSON response of the callback.

Actions

There are a number of actions that are defined for the Conversation API Zapier integration. These actions can be initiated in response to triggers, including Sinch-specific triggers.

Send a Message

This action allows you to send a message using the Conversation API. In order to send a message, you must populate the following fields:

Field Description
App The Conversation API app to be used to send the message.
How to target your recipient Either Sinch Contact ID or Channel Specific IDs. Determines whether the recipient is identified using the contact's unique contact ID or the contact's corresponding channel identity.
Sinch Contact ID Required if you set How to target your recipient to Sinch Contact ID. The unique ID of the contact to whom the message is to be sent.
Channels Required if you set How to target your recipient to Channel Specific IDs. The channels on which the message is to be sent. The available channels are based on the app you selected, and you can reorder the selected channels to set the channel priority for the message.
Channel Settings Properties and contact identification information that corresponds to each channel.
  • If you set How to target your recipient to Sinch Contact ID, and one or more channels configured on your Conversation API app have configurable channel-specific properties, those channels and their configurable properties are displayed. Depending on the configured channels, some of these properties may be required. For more information on channel-specific properties, see the channel support documentation.
  • If you set How to target your recipient to Channel Specific IDs, the channels you selected, and their configurable options, are displayed. Additionally, you must populate the recipient channel identity information for each channel. Also note that, if you populate the Channels field using dynamic data from a Zapier trigger, every channel configured for your Conversation API app will be displayed, and you only have to supply channel identity information for the channels to be used to send the message.
Message Type The type of message to be sent. Note that not all message types are supported on all channels. Depending on the message type you select, additional required fields may be displayed. For contextual information regarding additional required fields, as well as information regarding message type support by channel, see the Message types documentation.
Caution:

If you test this action, a test message will be sent to the specified contact. When testing, ensure that the specified recipient corresponds to a contact that is willing to recieve a test message, particularly if you are setting the recipient field using data provided by a Zapier trigger.

Register Opt-In

Note:

Currently, only the WhatsApp channel supports Opt-ins and Opt-outs.

This action allows you to register an Opt-in request for a specific contact. In order to register the Opt-in, you must populate the following fields:

Field Description
App The Conversation API app for which the Opt-in is to be registered.
Recipient's Number The MSISDN for which the Opt-in was sent. This number must be in the international E.164 format.

Register Opt-Out

Note:

Currently, only the WhatsApp channel supports Opt-ins and Opt-outs.

This action allows you to register an Opt-out request for a specific contact. In order to register the Opt-out, you must populate the following fields:

Field Description
App The Conversation API app for which the Opt-out is to be registered.
Recipient's Number The MSISDN for which the Opt-out was sent. This number must be in the international E.164 format.
Was this page helpful?
Still have a question? Ask the community.