Zapier Integration

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 (found on the customer dashboard) 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.

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:

Message Inbound, which corresponds to the MESSAGE_INBOUND callback trigger
Message Submit, which corresponds to the MESSAGE_SUBMIT callback trigger
Message Delivery, which corresponds to the MESSAGE_DELIVERY callback trigger
Event Inbound, which corresponds to the EVENT_INBOUND callback trigger
Event Delivery, which corresponds to the EVENT_DELIVERY callback trigger
Channel Event, which corresponds to the CHANNEL_EVENT callback trigger
Conversation Started, which corresponds to the CONVERSATION_START callback trigger
Conversation Stopped, which corresponds to the CONVERSATION_STOP callback trigger
Conversation Deleted, which corresponds to the CONVERSATION_DELETE 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
Contact Updated, which corresponds to the CONTACT_UPDATE callback trigger
Contact Identities Duplication, which corresponds to the CONTACT_IDENTITIES_DUPLICATION 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
Channel Specific/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. For example, the `WhatsApp Template` message type, which corresponds to active WhatsApp templates associated with your Conversation API app, is only supported by the `WhatsApp` channel. 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.