BulkSMS / Customer, Marketo Integration Guide, version 2.6, 2018/01/19. BulkSMS / Customer. Marketo Quick Start Integration Guide

Transcription

1 BulkSMS / Customer Marketo Quick Start Integration Guide 1

2 Assumptions: This guide assumes you have basic knowledge of Marketo and that you can create and edit Marketo Webhooks. Please contact if you need assistance. Required from you: If you don t yet have a username, then sign-up at After successful sign-up, you will have a few test credits in your account. Please send an 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 o The name of your Company 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 <user_key> (to be used later). The following optional details are only required if you are interested in status report updates and mobile originated messages or if you intend to send batch messages to leads that are members of a List or Program. Optional Marketo Client ID Marketo Client Secret REST Endpoint REST Identity Endpoint address for notifications 2

3 Provided to you: We will issue you with a <user key> that is linked to your selected BulkSMS username. - Your user key is a 36-character unique identifier in the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - Your <user_key> is unique to you and will be used in most Webhook configurations. - Don t make your <user_key> public or share it outside of your organization. We will also provide you with additional manuals and assistance as may be required for your Integration. 3

4 Marketo Webhook REST URI s: The general webhook URL has the following structure: Example: AA11E1C BD-A61A- 4CDEE0E2651E?password=****&lead_id=123 API functions follow on next pages: 4

5 Function: /webhook/v1/message/ Purpose: Sends an individual (triggered) SMS message from Marketo Usage: POST d={{lead.id}} 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. Eg. TheDentist Body: {"to":"{{lead.mobile Phone Number }}","body":"hello there {{lead.first Name }}"} Limits: No limits on outgoing messages, but status report updates and MO 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 update 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 transactional messages within this document, but are referred to as triggered messages from within Marketo. The sender_address must not contain any special characters or spaces. Advanced sender_address options can be specified in the body. See the full configuration manual for more details. 5

6 Function: /webhook/v1/batch/ Purpose: Sends bulk SMS message from Marketo Usage: POST nt> program_id=<int>&deduplication_id=<int32>&predicted_lead_count=<int> 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. Eg. TheDentist Body: {"body":"hello there [[lead.first Name ]]"} Note: the body structure { } does not require the to parameter. Limits: 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. The sender_address must not contain any special characters or spaces. Advanced sender_address options can be specified in the body. See the full configuration manual for more details. 6

7 Use of tokens for merged personalization of /Batch Messages This discussion about merge tokens only applies to /batch messages. Merge tokens in batch messages are enclosed in a set of double square braces E.g.: [[token]] Tokens can have optional attributes which control how they are processed. The following token attributes are supported. Attribute :default :if(>n) :If (unicode) Usage The substitute value to use if the data field is empty or if one of the attributes below evaluates to TRUE If the length of the merge field is greater than n, then use the default value instead. If the merge field contains Unicode characters, then use the default value instead. Example 1 (replace content with friend if name contains Unicode or longer than 5 characters) Dear [[lead.first Name:default=friend:if(unicode):if(>5)]] how are you? Results table First Name empty Bob Bob 美 Peter Peters Resulting message Dear friend how are you? Dear Bob how are you? Dear friend how are you? Dear Peter how are you? Dear friend how are you? Example 2 (remove name if it contains Unicode characters) Hello [[lead.first Name:default=:if(unicode)]] how are you? Results table First Name Empty Bob Bob 美 Peter Peters Resulting message Hello how are you? Hello Bob how are you? Hello how are you? Hello Peter how are you? Hello Peters how are you? 7

8 Handling of missing merge field data Each token is replaced by corresponding merge field content at runtime. For example, the [[lead.first Name]] might be replaced by John. [[lead.first Name]] and [[lead.last Name]] tokens can be blank, but all other tokens are expected to resolve with valid merge field data. Rows without merge field data will be skipped from the submission. Example 3 [[lead.company Name]] has been selected to take part in a survey. Results table Company Name Resulting message Empty ( This row will be skipped and no SMS will be sent for this lead ) Apple Corp Apple Corp has been selected to take part in a survey General notes about tokens and merge field data - Accepts friendly labels or API names as tokens. E.g. [[lead. First Name]] and [[firstname]] - Only supports tokens from the Lead object - Custom (non-standard) tokens must be specified as api names. i.e. Use [[sms_reply]] and not [[SMS Reply]] - Tokens must be enclosed in [[double square braces]] 8

9 BulkSMS HTTP Push Configuration These configuration details need to be set in the BulkSMS User Profile page, one for each account. Relay URL s MO Status Reports key> key> Sample Configuration 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 SMS Delivery Status SMS Reply SMS Program Id API Name sms_delivery_status sms_reply sms_programid *** Take note: The sms_programid API name above differs to other uses of program_id (which contain an underscore). 9

10 Webhook Sample Configuration You MUST also set a custom header as above. Custom header: Header: Content-type Value: application/json 10

11 Important: Set Request Token Encoding to None. 11