FoneAPI Channels
Public Beta
FoneAPI Channels are currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.
Public Beta products are not covered by a FoneAPI SLA.
Channels is the collection of third-party integrations that let you send and receive messages on multiple channels with the FoneAPI APIs you already use. Using Channels with FoneAPI makes it easy to reach your customers on new platforms, such as Facebook Messenger, Slack, LINE, Twitter, HipChat, and more.
Channels is available through the FoneAPI Marketplace; you can choose from a list of verified Channels and install them in a single click. Once installed, they allow you to send and receive messages with other communications platforms using the FoneAPI API.
Supported Products
FoneAPI Channels are currently supported by Programmable SMS and Notify. Click here to install specific Channels or request access to Channels in Developer Preview.
Channels in Public Beta:
Facebook Messenger
LINE
WhatsApp
Channels in Developer Preview:
RCS
Terms of Service
Channels are provided and supported by Channel providers in the FoneAPI Marketplace. As a part of the Channel installation process, you will be required to accept the Channel provider’s Terms of Service. Note that the Channel is provided under the Partner’s Terms of Service & Privacy policy. Channel-specific documentation can be found inside the Console under the Channel's catalog page.
Setup and Configuring a Channel
Installing a Channel
Getting started with Channels is simple. Available Channels are listed in the Channels Catalog inside the Console. To get started, click on the Channel and install it. This creates an instance of the Channel that you can configure with a Unique Name and enable for use in one or more FoneAPI products.
WhatsApp Beta
To get started with the Twilio API for WhatsApp, see the API docs here.
Authentication with Channel Provider & Configuration
In order to send and receive messages from a Channel, you must have an account setup within the specified platform. You will then authorize FoneAPI to send and receive messages on your behalf, thereby enabling access to each platform through the FoneAPI API.
Once a Channel is enabled, the next step is to authenticate the Channel instance with the Channel provider. This also links the Channel instance to a Channel-specific endpoint (such as a Facebook page) within that Channel. The specifics of this vary from Channel to Channel; please refer to Channel-specific documentation on the Channel detail page inside console.
Once a Channel is authenticated, you can now configure it to work with a FoneAPI API :
Channel address
Channel address
This is a unique identifier for the user facing Channel endpoint such as a Facebook Page. Channel addresses take the form of channel-provide:identifier. For instance, the Channel address for a Facebook Channel is messenger:
Callback URL
A URL where FoneAPI will POST each time a message is received by FoneAPI. The format of this request is the same as FoneAPI’s Inbound SMS FoneAPIML request. Non-relative URLs must contain a valid hostname (underscores are not allowed).
Creating multiple instances of a Channel
FoneAPI supports creating multiple instances of a Channel so that your application can use different Channel-specific endpoints. For example, this allows you to support sending / receiving messages from multiple Facebook pages, by creating and associating each Facebook page with an instance of the Facebook Channel.
Using the Channel
You use the same FoneAPI product APIs to send and receive messages from Channels. All you need to do is reference the Channel address you configured when you installed the Channel.
Once the Channel is configured, you need to select the FoneAPI product you would like to use the Channel with by checking the appropriate product checkbox under "Use In".
Channel Addresses
Each Channel uses a different unique identifier scheme to address users. The table below lists how users are identified by each supported Channel when used with FoneAPI APIs. For more details on endpoints and addresses for a given Channel, please refer to Channel-specific documentation on the Documentation page linked to from the Channel detail page inside console
address
Business phone number
whatsapp: {e
whatsapp: {e
See here to get started with WhatsApp
phone number, 1-11 character string (A-z, a-z, 0-9), Wireless SIM Sid
from
WhatsApp Beta
See the table below for the addressing scheme for WhatsApp:
address
Business phone number
whatsapp: {e
whatsapp: {e
See here to get started with WhatsApp
phone number, 1-11 character string (A-z, a-z, 0-9), Wireless SIM Sid
from
Programmable SMS
In order to use a Channel with Programmable SMS, you need to check the "Use In: Programmable SMS Inbound" checkbox.
Sending a Message
See the REST API: Sending a SMS or MMS or REST API: Messages page for details on how to use Channels via Programmable SMS APIs to send a message.
Here's an example of how you can send a message to Facebook Messenger using Programmable SMS:
curl -X "POST" \
--data-urlencode 'To=messenger:{Messenger User ID}' \
--data-urlencode 'From=messenger:{Facebook Page ID}' \
--data-urlencode 'Body=Would you like to play a game?' \
-u {Account Sid}:{Auth Token} \
https://api.twilio.com/2010-04-01/Accounts/{AccountSID}/Messages.json
Receiving a Message
In order to receive a message from a Channel that supports Programmable SMS, set the Callback URL under Configuration section once the Channel has been installed. This URL will receive a callback with the same format as Incoming SMS FoneAPIML Callbacks.
Managing Opt Ins, Opt Outs, and Consumer Preferences
Just like you are required to manage consumer opt-ins for your SMS applications, you are also responsible for managing consumer opt-ins to OTT platforms. Users of your application must explicitly grant you permission to message them in each unique channel. For example, consent to send someone a text message does not grant you permission to contact them via Messenger.
Similarly, you should respect consumers who opt-out on each platform. Each platform has their own method of opting out, which FoneAPI will normalize for you as much as possible. For example, consumers may text STOP to opt out of SMS, or they may block your application to stop messaging within an OTT channel. If a user opts out of one communication channel, you are NOT required to opt them out of all channels. You may treat each opt in and opt out independently.
