This activity lets you trigger outbound SMS when a structured inbound payload (API Request) is received. This requires your workspace to have at least one authorized API Key. The steps below detail how to create an API Key, how to configure the send SMS from a Web Service Activity, and information about the expected payload.
A: Generating an API Key
There are two ways around this. You can generate the key manually or have the system do this for you automatically as explained below.
Step 1: Click the settings cog in the top-right of the screen, and select 'API web services and Integrations'.
Step 2: Click 'Connect a web service' and select 'Connect an external web service to your workspace' to create a new Frontline API Integration.
Step 3: Give the API Key a name and Save.
Note: There is an option here to 'Create a default Web Service to SMS Activity'. Check this box to create the required Activity and it will appear in the Activities list with the name you have given this Frontline API Integration.
You can go directly to the Activities page to view and edit details so this is great shortcut if all you want the API for is to route all of your API Requests to SMS. If you do this you can skip direct to Section C below.
Your newly generated API Key will now be shown in your list of integrations as seen on the image below. You will need to use this API Key with your API Requests in Section C. You will also need to make a note of the URL of the given endpoint https://cloud.frontlinesms.com/api/1/webhook.
B: Creating the Send SMS from a Web Service Activity
Note: if you auto-created this Activity above you can skip now to Step C
Step 1: On the Activities page, click 'Create activity' to get started and click 'Send SMS from a web service' from the Activity selector.
Step 2: A page will open where you can specify the details for the Activity:
Step 3: Give a name for the Activity (1).
Step 4: Optionally specify whether you want only one specific API Key to be able to send messages using it, or whether all active API Keys can trigger it (2).
Step 5: (Optional) In inputs 3. and 4. In the advanced options in the image above, you can specify a tag to be applied to all API Requests received that result in an SMS being sent, and choose a specific connection that the generated SMS messages will be sent through.
C: Triggering your activity
Once you have an active API Key and an API Request to SMS Activity, you can send SMS by submitting requests to the FrontlineSMS endpoint URL:
https://cloud.frontlinesms.com/api/1/webhook
The expected format is POST, with the 'Content-Type' header set to 'application/json', and a JSON payload as the body. There is a specific payload structure expected by the Activity as is specified below:
{
"apiKey": "your-API-Key",
"payload": {
"message":"Hi people!",
"recipients":[
{ "type":"smartgroupName", "value":"Kenyans" },
{ "type":"contactName", "value":"Sam Camper" },
{ "type":"contactName", "value":"Bobby" },
{ "type":"contactName", "value":"Darwin" },
{ "type":"groupName", "value":"Friends" },
{ "type":"mobile", "value":"+1234567890" },
{ "type":"mobile", "value":"+1234567891" }
]
}
}
As shown in the example above, the payload should have two properties, message and recipients.
View sample PHP code for using the API to send an SMS.
Message
The message property should be a String, representing the text of the SMS that will be sent to each recipient. Unless there is a specific restriction for the aggregator or mobile network used to send out the SMS, this payload can be up to 1600 characters. Frontline will handle any multi-part messaging logic required when sending out the SMS.
Recipients
Recipients should be an array, in which each element is an object with a 'type' and 'value' property. The valid types are:
- smartgroupName: The corresponding value should be the name of a smartgroup in your Frontline workspace
- groupName: The value should be the name of a group in your Frontline workspace
- contactName: The value should be the name of a contact in your Frontline workspace
- mobile: The value should be an international-format mobile number without decorative spaces or dashes. This lets you send messages to recipients without referring to the Frontline people database
There is no restriction on the number of elements in the recipients list, and thus no restriction on the number of SMS that can result from one SendSmsPayload. There needs to be at list one type/value in the recipients list.
0 Comments