BULKSMS MARKETO GATEWAY - INTEGRATION GUIDE - MARKETO LAUNCHPOINT
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
BulkSMS Marketo Gateway
Integration Guide
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 1
Contents
Introduction ............................................................................................................................................ 4
About the BulkSMS Gateway for Marketo.......................................................................................... 4
Advanced Group Messaging – Key Features....................................................................................... 4
Use any or all of our other products and tools from the same BulkSMS account.......................... 5
STEP 1 – Register with BulkSMS.com ...................................................................................................... 6
Register a new BulkSMS account ........................................................................................................ 6
Get FREE SMS test credits and your unique .................................................................... 7
STEP 2 – create a Webhook for a trigger campaign................................................................................ 8
URL: ................................................................................................................................................... 10
TEMPLATE: ........................................................................................................................................ 11
STEP 3 – Create a trigger to Send an SMS............................................................................................. 12
Create the Smart List ........................................................................................................................ 14
Configure the Flow ............................................................................................................................ 15
Schedule the trigger .......................................................................................................................... 16
Basic Testing...................................................................................................................................... 18
Diagnostics and additional Reporting ............................................................................................... 20
Check the basics ............................................................................................................................ 20
Check the Marketo configuration ................................................................................................. 21
Check the BulkSMS configuration ................................................................................................. 23
Further Development ....................................................................................................................... 25
Extend the sample ........................................................................................................................ 25
Reply messages and status reports can be sent back to Marketo in real time ............................ 25
STEP 4 – Create a Webhook for a Bulk Campaign (optional) ................................................................ 26
About Bulk Campaigns ...................................................................................................................... 26
URL: ................................................................................................................................................... 28
TEMPLATE: ........................................................................................................................................ 29
STEP 5 - Update Marketo Leads using callbacks (optional*) ................................................................ 30
About Callbacks ................................................................................................................................. 30
Marketo Configuration ..................................................................................................................... 30
Create Custom Fields on Lead object................................................................................................ 31
Customize the Lead view to show the new custom Fields ............................................................... 34
Configure BulkSMS Callback URI’s .................................................................................................... 36
Summary ............................................................................................................................................... 37
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 2
Appendix A : BulkSMS Marketo Gateway API Reference ..................................................................... 38
Marketo Webhook REST URI’s: ......................................................................................................... 38
Function: /webhook/v1/message/ ............................................................................................... 39
Function: /webhook/v1/batch/ .................................................................................................... 40
Sender Address Specification (also known as the sender ID) ........................................................... 42
Sender Address vs Sender ID ........................................................................................................ 42
Sender address usage ................................................................................................................... 42
Custom sender address................................................................................................................. 42
Applying for custom sender addresses ......................................................................................... 42
Using the custom sender address ................................................................................................. 43
Notes from the API specification .................................................................................................. 44
[[Tokens]] within {{Tokens}}.............................................................................................................. 45
Smart Tokens .................................................................................................................................... 46
Token Field (no attributes)............................................................................................................ 47
Token Field Attributes :default ..................................................................................................... 47
Token Field Attributes :if(>n) ........................................................................................................ 48
Token Field Attributes :if(unicode) ............................................................................................... 49
Token Field Attributes :if(unicode):if(>n) ..................................................................................... 50
BulkSMS HTTP Push Configuration ................................................................................................... 51
Sample Configuration ................................................................................................................... 51
Marketo Lead Updates ..................................................................................................................... 51
Appendix B: Other BulkSMS Products .................................................................................................. 52
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 3
Introduction
About the BulkSMS Gateway for Marketo
The BulkSMS Gateway for Marketo was designed for advanced SMS integration between Marketo
and BulkSMS. This guide covers the basic integration steps, and should be sufficient for most
common SMS messaging needs.
Advanced Group Messaging – Key Features
The BulkSMS Marketo Gateway can very efficiently send bulk messages to large numbers of leads.
Key Features
• Quick and Easy. Basic setup (STEP 1 & 2) can be completed in minutes.
• Send up to 30,000 messages in a single submission
• Long messages up to 1536 characters in length
• Send messages that contain Unicode and special characters
• Two-way messaging – mobile originated messages posted to Marketo in real-time
• Status report updates sent periodically using minimal Marketo API calls
• Allows tokens within tokens for bulk messages
• Smart tokens (to prevent long or Unicode messages because of token content)
Plus!
• Send to any mobile network internationally
• Local replies
• Competitive pricing
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 4
Additional Features can be discussed with your account manager or someone in our support team.
• Schedule message for later delivery (up to 1 year in advance)
• Customizable sender ID – like your brand or company name or alternate reply number.
• Incoming long numbers – for mobile originated messaging.
Contact support@bulksms.com if you need more information, and please mention your specific
requirements so that the request can be allocated to the correct person / team.
Use any or all of our other products and tools from the same BulkSMS account.
You can use any or all of our products from the same BulkSMS account, or you can create multiple
accounts for different use cases or internal departments. You can also easily transfer credits
between accounts or have a primary (parent) account that sponsors multiple sub accounts.
See the Appendix as the end of this document
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 5
STEP 1 – Register with BulkSMS.com
Register a new BulkSMS account
Go to www.bulksms.com and click the Sign Up button to register a new account.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 6
Get FREE SMS test credits and your unique
After successful sign-up, you will have a few test credits in your account.
Please send an e-mail To: support@bulksms.com with the following information.
Subject Line: Marketo Integration Request
And then include the following in the body of the mail
o The name of your Company
o Your BulkSMS username (this is case sensitive)
We will then load some additional free test credits to your account and reply to your mail with a
unique (to be used later).
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 7
STEP 2 – create a Webhook for a trigger campaign
From within Marketo, go to the Admin, Integration, Webhooks, and create a New Webhook.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 8
Tip. If you’re reading this document in electronic format, then you can copy the URL and Template
text on the next page for easy pasting when you create your Webhook.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 9
Enter the Webhook details as shown in the screens above.
Custom header:
Header: Content-type
Value: application/json
URL:
(you can copy and paste this URL)
https://gateway.bulksmsmessenger.com/webhook/v1/message/?password
=&leadid={{lead.ID}}
Replace the token with the User Key that was e-mailed to you as part of your BulkSMS
Registration and support@bulksms.com request. This user key is typically 36 character in length and
is in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx. Replace the token
with the password that you selected when you registered your BulkSMS account in STEP 1.
Do not include the < angle brackets >
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 10TEMPLATE:
(You can copy and paste this. Modify and change your message as you feel necessary)
{"to":"{{lead.Mobile Phone Number:default=edit me}}","body":"Hello {{lead.First Name:default=edit
me}}. Your experience has been booked! We'll contact you shortly with the detail. Please reply to
this SMS if you have any queries."}
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 11STEP 3 – Create a trigger to Send an SMS
There are many ways to create a trigger to send an SMS. The following is just one example. You
should implement what works best in your business.
From the main Marketo options menu, click Marketing Activities, New, New Smart Campaign
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 12Just enter some basic descriptive information. The Folder is selected from a drop-down list of
available folders. Click the Create button to continue.
Select the Smart List option.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 13Create the Smart List
Drag the ‘Data Value Changes’ item from the list on the right and drop in into the main work area.
That should create a ‘Data Value Changes’ process box. Select the ‘Mobile Phone Number’ item from
the ‘Attribute’ list.
When done, click the ‘Flow’ tab to continue.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 14Configure the Flow
(1) Drag the ‘Call Webhook’ item from the list on the right, and drop it into the main work area.
(2) Next, click the ‘Webhook’ drop-down list, and select the Webhook you created in STEP 2.
(3) When ready, click Schedule tab to continue.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 15Schedule the trigger
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 16(1) This is an optional setting. By default, the Lead will only be included once in the campaign,
so because we’re testing and likely to want to send multiple messages, you can optionally
change the trigger option from ‘only once’ to every time’.
(2) The campaign will not work until activated. Click the ‘Activate’ button to activate the
campaign.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 17Basic Testing
Now that you’ve done the configuration, it’s easy to run a test or two. Follow these steps;
1. Create a new Lead
2. Edit the Lead and add a mobile to the Mobile: field
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 183. The Lead should be auto-saved after you move to the next field or another part of the
screen. This should trigger the webhook to be called, which in turn should result in message
being sent to the designated mobile phone.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 19Diagnostics and additional Reporting
If you followed the steps on the previous pages, then the SMS’s should be delivered to the
designated mobile phones when the associated Webhooks are triggered. If the SMS’s are not being
delivered, then there’s a few things to check.
Check the basics
The obvious first steps are to ensure that;
- you have a valid BulkSMS account with credits
- you’ve correctly entered the in the Webhook configuration screen, and entered
the correct case sensitive password.
- The mobile number is valid and begins with a country code. Eg 4412345678 (for the UK), or
112345678 (for the US) etc.
- The campaign has been Activated
- Qualification Rules set to ‘Every time’ – see page 17
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 20Check the Marketo configuration
If those items checkout, then you can look at the Marketo campaign Results screen. The Results
screen will provide you with activity history. If no activity, then it means the Webhook is not being
triggered. If there is activity, the view the detail to determine if the message was sent. See the
following screen shots.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 21The Activity Details screen will show if the message was sent, as well as any success or error
messages / codes. For assistance, please contact support@bulksms.com
Typical Response code
The only valid response is 201 (meaning CREATED). Any other code will typically be an error. See the
table below for guidance. Contact support@bulksms.com if you need assistance.
Code Meaning Reason
400 Bad Request Something in the request is invalid..
403 Forbidden The request indicated an action that is not allowed.
Unprocessable
422 The request entity is invalid
Entity
429 Throttled …… http://tools.ietf.org/search/rfc6585
Internal Server
500 Something unrelated to the request is broken
Error
Service The server is refusing to handle your request. You would normally only see
503
Unavailable this status as part of a throttled response, but it may appear in other cases.
Table 1
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 22Check the BulkSMS configuration
If the response code in the activity detail screen is 201, then it means that the message was sent to
and accepted by BulkSMS. So, to investigate further, log in to your BulkSMS account and click on the
‘View’ item in the ‘SENT MESSAGES’ area.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 23Any sent messages will be displayed in the Message history page, along with delivery a delivery
status. The delivery status is descriptive and should help diagnose any delivery issues.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 24Further Development
Extend the sample
The steps in this guide were created to get you started with a basic messaging sample. This sample
can be extended for much more sophisticated use cases.
Messages are 2-way. Recipients can reply to SMS messages and these replies will be accessible from
your BulkSMS Inbox. You can view your Inbox messages using any of our products, like the Web Site,
via our API, or using the Desktop Messengers for Windows or Apple Mac, or the iOS App.
Visit www.bulksms.com/products to for more information.
Reply messages and status reports can be sent back to Marketo in real time
If you are interested in having reply messages and delivery status updates sent back to Marketo,
then you can continue with the optional configuration in a later section.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 25STEP 4 – Create a Webhook for a Bulk Campaign (optional)
About Bulk Campaigns
This step is optional. Bulk Campaigns allow you to send personalized messages to up to 30,000 leads
in a single submission. Bulk campaigns are useful for when you want to send to large numbers of
contacts at one time, especially if your message is time critical and you are receiving delivery reports
and you have restrictions or limitations on your daily REST API quota.
Please contact support@bulksms.com if you’re unsure or need more information.
Sending to a large list of leads is as easy as sending to a single lead, but instead of specifying the ID
of the lead you want to send to, you specify the ID of the list or program.
The BulkSMS system will do all the hard work, and status report and replies will be pushed back to
your Marketo instance automatically.
From within Marketo, go to the Admin, Integration, Webhooks, and create a New Webhook.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 26Tip. If you’re reading this document in electronic format, then you can copy the URL and Template
text on the next page for easy pasting when you create your Webhook.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 27Enter the Webhook details as shown in the screens above.
Custom header:
Header: Content-type
Value: application/json
URL:
(you can copy and paste this URL)
https://gateway.bulksmsmessenger.com/webhook/v1/batch/?password=<
bulksms_password>&listid={{list.ID}}
Replace the token with the User Key that was e-mailed to you as part of your BulkSMS
Registration and support@bulksms.com request. This user key is typically 36 character in length and
is in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx. Replace the token with the
password that you selected when you registered your BulkSMS account in STEP 1.
Do not include the < angle brackets >
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 28TEMPLATE:
(You can copy and paste this. Modify the message as required)
{"body":"Hello [[lead.First Name:default=edit me]]. This is a test message to a list of your choice"}
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 29STEP 5 - Update Marketo Leads using callbacks (optional*)
* NOTE: optional for STEP 2 (trigger campaign), but required for STEP 4 (bulk campaign)
About Callbacks
This step is optional*. Callbacks are used to push BulkSMS reply messages and status updates to
Marketo, thereby updating the Lead record that was originally associated with the outgoing SMS.
Delivery Status Updates
So for example, if an SMS is successfully sent to a Lead, then the delivery status of that SMS can be
written back to a custom field on the Lead as proof that the message was delivered, or a failure
message if unsuccessful.
Reply or Mobile Originated (MO) Messages
Similarly, if the recipient of the SMS sends a reply SMS, then that reply can also be written to a
custom field on the Lead record.
You can then of course create other triggers to perform another action in the workflow in response
to such updates.
Marketo Configuration
To configure these callbacks, you need to obtain Marketo API credentials so that BulkSMS can make
authenticated calls to your instance.
The steps for this can be found here: http://developers.marketo.com/rest-api/
At the end of the configuration process, you should have the following information to hand.
- Marketo client ID
- Marketo client secret
- REST endpoint
- REST identity endpoint
Please send this information to support@bulksms.com with the subject line Marketo / BulkSMS
callback. Please also remember to mention your username. You can copy/paste the template below
into a new empty e-mail message. Remember to include all the required information.
To: support@bulksms.com
Subject: Marketo /BulkSMS callback
Message Body: Hello BulkSMS support team. Please update my Marketo configuration with the
following information.
Username :
:
Marketo client ID :
Marketo client secret :
REST endpoint :
REST identity endpoint :
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 30Create Custom Fields on Lead object
The next step is to create two custom fields on the Lead object. These will be used to store the
delivery status and reply message.
The field must be named as follows and names are case sensitive.
Field Name API Name
SMS Delivery Status sms_delivery_status
SMS Reply sms_reply
Table 2
For instructions on how to create custom fields, simply follow these detailed steps in the Marketo
Blog. Steps 1 to 5 are relevant to this integration. The steps have been copied and included below
for your convenience.
http://developers.marketo.com/blog/create-a-custom-field-in-marketo-and-update-this-field-via-
api/
1. Under Admin, click on Field Management.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 312. Click the New Custom Field button.
3. Choose the field Type. This will change how it is rendered in Smart Lists and Forms in Marketo.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 324. Enter the Name as you want it to appear in Marketo.
In this case, you should be naming the field as ‘SMS Delivery Status’ as described in Table 2 on page
31. Repeat these steps for the ‘SMS Reply’ field.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 33Customize the Lead view to show the new custom Fields
Once the new fields have been created, it would be useful to add them to the Leads view. That way,
it’s easy to see the delivery status and any reply message at a glance.
To add the custom fields, follow these next easy steps.
You can either Edit the Default view or optionally create a new View.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 34Select the fields you want by adding moving columns from the Hidden Columns table to the Visible
Columns table.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 35Configure BulkSMS Callback URI’s
The final step is to activate callbacks on the BulkSMS system. The BulkSMS support team would most
likely already have completed this step for you, but the procedures are listed in any event in case
you need to make changes at a later stage.
Log in to your BulkSMS account as www.bulksms.com, then select ‘Your Profile’
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 36Set the relay URL fields. You can copy and paste the template values below.
Field Value
MO Relay https://gateway.bulksmsmessenger.com/api/v1/callback/mo/
Report https://gateway.bulksmsmessenger.com/api/v1/callback/statusreport/
Relay
Summary
This concludes basic the integration steps. These procedures are all very quick and effortless and you
can be up and sending messages within an hour.
If you need assistance or have question, please send an e-mail to support@bulksms.com.
We will general respond within the hour, but may take longer during busy periods or after hours.
Alternatively, please visit the Contact page on our website for additional contact details.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 37Appendix A : BulkSMS Marketo Gateway API Reference
Marketo Webhook REST URI’s:
The general webhook URL has the following structure:
https:// //?
There are two functional s;
For testing:
Note: this endpoint might not always be available. It is not intended for you to test your software.
You are encouraged to test your software on the production URL. This test URL exists so that you can
test your software against pending release of the BulkSMS Marketo Gateway. We will generally
notify you before we release updates which might affect you and will thus require testing against
this URL.
gatewayqa.bulksmsmessenger.com
For production:
gateway.bulksmsmessenger.com
Example:
https://gateway.bulksmsmessenger.com/webhook/v1/message/ AA11E1C9-
8804-47BD-A61A-4CDEE0E2651E?password=****&lead_id=123
API functions follow on next pages:
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 38Function: /webhook/v1/message/
Purpose:
Sends an individual (triggered) SMS message from Marketo
Usage:
POST
https://gateway.bulksmsmessenger.com/webhook/v1/message/?p
assword=****&leadid={{lead.ID}}
Note: Ensure that you replace with your unique user key (issued by BulkSMS at
registration)
Query Parameters:
Parameter Required Comments
password Yes BulkSMS account password
lead_id Yes ID of the lead the message is being sent to
sender_address Optional Existing sender ID (see sender address topic)
Body:
{"to":"{{lead.Mobile Phone Number }}","body":"Hello there {{lead.First Name }}"}
Limits: No limits on outgoing messages, but status report updates and mobile originated messages
are restricted in quantity by the daily Marketo REST API quota. There might also be time restrictions
/ considerations. Messages might be delayed for large batches because Marketo might need to
share limited resources between many competing requests.
Comments: The lead_id is required so that status reports and replies can update the same lead
that was specified in the outgoing message. Status reports and MO messages are pushed back to
Marketo in real-time.
While the outgoing message doesn’t use any Marketo REST API calls (a limited resource), the status
report updates and replies do consume REST API calls.
This function is easy to implement but has limited bulk capacity, mainly because Marketo will post
messages individually.
These messages are referred to as trigger campaign messages from within Marketo.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 39Function: /webhook/v1/batch/
Purpose:
Used to sends bulk SMS message from Marketo
Usage:
POST
https://gateway.bulksmsmessenger.com/webhook/v1/batch/?pas
sword=****&list_id=|program_id=&deduplication_id=&p
redicted_lead_count=
Note: Ensure that you replace with your unique user key (issued by BulkSMS at
registration)
Query Parameters:
Parameter Required Comments
password Yes BulkSMS account password
list_id One of * ID of the list this message must be sent to
program_id One of * ID of the program this message must be sent to
deduplication_id Yes Prevents duplicates from being sent
predicted_lead_count Optional Prevents accidental wrong group messages
sender_address Optional Existing sender ID (see sender address topic)
Body:
{"body":"Hello there [[lead.First Name ]]"}
Note: the body structure { } does not require the “to” parameter. Also note that /batch tokens are
enclosed in [[square braces]].
See page 42 for a discussion on Sender Address Specification (also known as the sender ID)
Sender Address vs Sender ID
Note: Sender address in this documentation and sender ID in other documentation are one and the
same thing. The term sender address is used to align more closely with the underlying API
terminology.
Sender address usage
The sender address determines the content displayed in the FROM portion of an SMS message.
Messages can be replied to by default, so the FROM portion will contain a reply mobile number. This
number would generally be one from a pool of BulkSMS.com owned local numbers. Replies to
messages are routed back to the Inbox of your BulkSMS.com account, and after full integration can
also be pushed back to Marketo.
Custom sender address
The reply number can be overwritten with a custom sender address, which could be a short-code, a
different reply number or other alpha numeric text, such as a brand or campaign name.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 40Limits:
30,000 messages in a single submission.
Comments:
This function is used to send bulk personalized messages to the leads contained in the specified List
or Program. It is advised to make use of the predicted_lead_count feature to prevent
accidentally sending the message to the wrong group.
Duplicate mobile numbers are eliminated by accepting the first, then skipping subsequent leads with
the same mobile number. The order for extraction is undetermined.
Replies are pushed back to Marketo in real-time. Status reports are accumulated and pushed back to
Marketo periodically.
Multipart replies are viewable in the Marketo lead Activity Log
Resubmissions will require a new deduplication_id if any of the body details or other
parameters are changed.
Important: In case this is not already clear, trigger (/message) campaigns call the
associated webhook once for each message recipient, but bulk (/batch)
campaigns should only call the webhook once for the entire campaign, regardless
of the number of members in the program or list. This is because /batch
campaigns use the program or listid provided to extract the lead members from
the campaign to enable a single bulk submission. Note: There is a maximum limit
of 30,000 members per submission.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 41Sender Address Specification (also known as the sender ID)
Sender Address vs Sender ID
Note: Sender address in this documentation and sender ID in other documentation are one and the
same thing. The term sender address is used to align more closely with the underlying API
terminology.
Sender address usage
The sender address determines the content displayed in the FROM portion of an SMS message.
Messages can be replied to by default, so the FROM portion will contain a reply mobile number. This
number would generally be one from a pool of BulkSMS.com owned local numbers. Replies to
messages are routed back to the Inbox of your BulkSMS.com account, and after full integration can
also be pushed back to Marketo.
Custom sender address
The reply number can be overwritten with a custom sender address, which could be a short-code, a
different reply number or other alpha numeric text, such as a brand or campaign name.
The sender address is limited to 11 characters and shouldn’t contain any punctuation, spaces or
special characters.
Applying for custom sender addresses
BulkSMS.com controls the sender address to help prevent fraud and encourage responsible
messaging. You can only make use of a custom sender address that has been approved for your
BulkMS.com account.
You can apply for custom sender address (sender ID) approval by following the appropriate links
after logging in to your BulkSMS account, or from the contact page
https://www.bulksms.com/contact/
If you attempt to use a sender address in your Marketo webhook or integration that has not already
been authorized for your account, then the message will be sent from a BulkSMS branded address,
such as ‘bulksms.com’. Be sure to test first before sending bulk messages!
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 42Using the custom sender address
A basic custom sender address can be specified as a query parameter in the Marketo Webhook.
The syntax is:
sender_address=
Example of usage:
sender_address =CocaCola
Full usage:
https://gateway.bulksmsmessenger.com/webhook/v1/message/?p
assword=****&leadid={{lead.ID}}&sender_address=TheDentist
The sender address query parameter can be used in both /message (trigger) and /batch (bulk) type
messages.
The sender address is not currently URL decoded, and is limited to basic alpha numeric text.
More complex sender address details can be specified as a structured ‘from’ object in the payload
section of the webhook request. This follows the format of the JSON API specification here:
http://developer.bulksms.com/json/v1/
The general syntax is:
{
"from": {"type":"ALPHANUMERIC","address":"BobBuilder"},
"to": "+4478812345678",
"body": "Hello World!"
}
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 43Notes from the API specification
The value of this property is ignored if your account profile does not allow you to specify the sender.
“type”: The type of the sender id.
"INTERNATIONAL" "ALPHANUMERIC" "SHORTCODE" "REPLIABLE"
If you want BulkSMS to collect replies to this message on your behalf, specify the type as REPLIABLE.
If the recipient is in a country where BulkSMS does not have a local reply number, the reply may
incur costs that are more expensive than sending a local SMS in that country. If you operate a service
from a shortcode in a locale that allows messaging from such a shortcode, you can specify
SHORTCODE for the type.
“address”: The address of the sender id.
The validation for this field depends on the value of the type. INTERNATIONAL can start with +. It has
a maximum length of 15 digits, and has to be longer than 6 digits. ALPHANUMERIC has a maximum
length of 11 characters. SHORTCODE has a maximum length of 6 digits. REPLIABLE should not specify
a value here.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 44[[Tokens]] within {{Tokens}}
Tokens used in /Batch messages are specified within [[double square braces]]. These tokens can be
used in Marketo ‘My Tokens’.
Examples of use.
This makes it useful in situations where the message detail is specified external to the webhook such
that a single webhook can be used across multiple campaigns.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 45Smart Tokens
Tokens used in /Batch messages are specified within [[double square braces]]. These tokens can also
contain attributes that changes the behaviour of the token at submission time.
For example, if you want to ensure that a message is not longer than a certain length, then you can
specify a maximum length for a token, so that if the merged content for that token exceeds the
specified length, then the token will use a default specified value. There is a similar attribute for
Unicode characters.
In Summary, tokens can contain the following attributes.
:default=
:if(>n)
:if(unicode)
Usage examples follow.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 46Token Field (no attributes)
[lead.First Name]]
Example:
“Hello [[lead.First Name]]. How are you?”
Lead.First Name Message
Bob “Hello Bob. How are you?”
Token Field Attributes :default
:default= the default value to use if there is no merge content
Example:
“Hello [[lead.First Name:default=friend]]. How are you?”
Lead.First Name Message
Bob “Hello Bob. How are you?”
(empty) “Hello friend. How are you?”
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 47Token Field Attributes :if(>n)
:if(>n) - use the default value if the field length is greater than n
Example:
“Hello [[lead.First Name:default=friend:if(>5)]]. How are you?”
Lead.First Message
Name
Bob “Hello Bob. How are you?”
(empty) “Hello friend. How are you?”
Peter “Hello Peter. How are you?”
Annabel “Hello friend. How are you?”
Bob 美 “Hello Bob 美. How are you?” (this message is now Unicode)
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 48Token Field Attributes :if(unicode)
:if(unicode) - use the default value if the field contains one or more Unicode characters
Example:
“Hello [[lead.First Name:default=friend:if(unicode)]]. How are you?”
Lead.First Message
Name
Bob “Hello Bob. How are you?”
(empty) “Hello friend. How are you?”
Peter “Hello Peter. How are you?”
Annabel “Hello Annabel. How are you?”
Bob 美 “Hello friend. How are you?”
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 49Token Field Attributes :if(unicode):if(>n)
:if(unicode):if(>5) - use the default value if either condition is met
Example:
“Hello [[lead.First Name:default=friend:if(unicode):if(n>5)]]. How are you?”
Lead.First Message
Name
Bob “Hello Bob. How are you?”
(empty) “Hello friend. How are you?”
Peter “Hello Peter. How are you?”
Annabel “Hello friend. How are you?”
Bob 美 “Hello friend. How are you?”
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 50BulkSMS HTTP Push Configuration
These configuration details need to be set in the BulkSMS User Profile page, one for each account.
Relay URL’s
MO https://gateway.bulksmsmessenger.com/api/v1/callback/mo/
Status Reports https://gateway.bulksmsmessenger.com/api/v1/callback/statusreport/
Sample Configuration
https://gateway.bulksmsmessenger.com/api/v1/callback/mo/AA11E1C9-8804-47BD-
A61A-4CDEE0E2651E
Marketo Lead Updates
Status report and MO messages (replies) currently update custom fields of the originating lead. This
is for demonstration and testing purposes. More advanced updating can be achieved during full
integration.
To enable the above to work, please create the following custom fields on the Lead object.
API Names are case sensitive.
Field Name API Name
SMS Delivery Status sms_delivery_status
SMS Reply sms_reply
SMS Program Id sms_programid
*** Take note: The sms_programid API name above differs to other uses of program_id (which
contain an underscore).
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 51Appendix B: Other BulkSMS Products
- Desktop Messenger for Windows, Apple Mac
- Salesforce Messenger
- JSON REST API
- Web Interface
- iOS App
- E-mail to SMS
Many of our clients use multiple products to cover all their SMS messaging needs.
The Desktop Messengers are very user friendly and they are particularly useful for ad-hoc
messaging. The Desktop Messenger for Windows is the ideal tool for sending to large or huge
groups, and can link to or reference external ODBC data-sources, such as SQL Server, Excel, MS
Access, My Sql and many proprietary products that share data via ODBC.
The iOS App runs on most modern iPhone and iPads. It allows you to send to online groups that can
contain as much as 10,000 contacts per group.
Please visit www.bulksms.com/products for more information.
© Celerity Systems (Pty) Ltd 2018, version 2.6, 2018/01/21
Page | 52You can also read
