Example Integration Scenarios

Modified on Mon, 2 Sep at 1:37 PM

Sending a Plain SMS

Your Application
Tall Bob
Credentials for the Tall Bob API must be included with every request, API credentials must be passed in the request header using Basic Auth. Please make sure that the API credentials point to the correct endpoint
API Credentials can be accessed via the Tall Bob Platform, instructions on how to retrieve them are outlined here
Sending a Plain SMS Message can be completed using this endpoint

End Point: Reference Documentation
URL: https://api.tallbob.com/v2/sms/send

Example Request Headers:
Content-Type: application/json
Authorization: Basic NTcwYWU0OWU1ZmZjNjpvd0thVXVhNDYwc###


Example Request Payload:
{
"to": "61412345678",
"message": "This is a Test Message",
"reference": "AAA111",
"from": "TallBob"
}
  • Payloads must be well formed and JSON Encoded to be accepted
  • "to" value must be in E.164 format
  • "reference" can be used to store a unique reference for this message, any event-based data such as delivery receipts or click tracking events etc returned to your application via a webhook will include this reference Example.

Tall Bob will take and process the request doing some basic checks to ensure that the request is well formed, expected response will be one of the below

Example Responses

Message Queued for Delivery
{
"sms_id": "38eca59a-4e15-11ea-ac5f-067453a7f748",
"status": "queued",
"created": "2020-02-13 03:59:24",
"price": 0.08,
"unicode": false,
"length": 25,
"num_segments": 1,
"from": "TallBob",
"to": "61429967196",
"message": "The yacht is on the river",
"reference": "AAA111"
}
The recipient is Opted Out of receiving SMS messages
{
"message": "recipient opted out",
"code": 9998
}


Tracking your message delivery
In order to receive updates on the processing of messages in real-time your Application will need to have a publically accessible URL Endpoint that Tall Bob can communicate with.


  • The URL specified must be using HTTPS to ensure that data is sent in a secure format
  • Tall Bob will not send event data to unsecured HTTP endpoints due to the possible presence of PII




Tall Bob tracks a set of events related to the lifecycle of an SMS message which can be sent back to your application.

Typical events that may be received are:
  • Message Sent
  • Message Delivered
  • Message Failed
Example Payload:
{
"eventType": "message_pushed",
"timestamp": 1583377886,
"eventID": "018bfd96-5e8f-11ea-9281-0634275fc628",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-bbe2-029c13ef7f22",
"recipient": "61411118802",
"address": "61411118802",
"status": "ACCEPTED",
"externalID": "AAA-111",
"reference": "BBB-222"
}

You can register to receive even data back in one of two ways
  1. Via the Tall Bob Platform as outlined here
  2. By API request as outlined here
For more information on how to monitor the delivery status of your messages please see here


Sending an MMS

Your Application
Tall Bob
Credentials for the Tall Bob API must be included with every request, API credentials must be passed in the request header using Basic Auth. Please make sure that the API credentials point to the correct endpoint
API Credentials can be accessed via the Tall Bob Platform, instructions on how to retrieve them are outlined here
Sending a Plain SMS Message can be completed using this endpoint

End Point: Reference Documentation
URL: https://api.tallbob.com/v2/mms/send

Example Request Headers:
Content-Type: application/json
Authorization: Basic NTcwYWU0OWU1ZmZjNjpvd0thVXVhNDYwc###


Example Request Payload:
{
"from": "TallBob",
"to": 61400000000,
"url": "https://example.com/file.jpg",
"subject": "here is a picture of a cat",
"message": "Hic repellendus libero quia aperiam aliquam quis. Eos voluptatem expedita nostrum possimus dicta. Ut assumenda non enim aliquid aut quis est. Fugit aliquid expedita quos eos sequi in et.",
"reference": "ABC-123"
}
  • Payloads must be well formed and JSON Encoded to be accepted
  • "to" value must be in E.164 format
  • "reference" can be used to store a unique reference for this message, any event-based data such as delivery receipts or click tracking events etc returned to your application via a webhook will include this reference 
  • "URL" must point to the media you want to be included in the message and be accessible to the Tall Bob Servers.

Tall Bob will take and process the request doing some basic checks to ensure that the request is well formed, expected response will be one of the below

Example Responses

Message Queued for Delivery
{
"mms_id": "62d9bb8e-e8ea-11ea-87fd-067453a7f748",
"created": "2020-08-28 04:53:16",
"status": "queued",
"from": "TallBob",
"to": "61400000000",
"subject": "here is a picture of a cat",
"message": "Hic repellendus libero quia aperiam aliquam quis. Eos voluptatem expedita nostrum possimus dicta. Ut assumenda non enim aliquid aut quis est. Fugit aliquid expedita quos eos sequi in et.",
"reference": "ABC-123",
"url": "https://example.com/file.jpg"
}
The accepted format for MMS Media are:
  • .gif
  • .png
  • .jpg, .jpeg
  • .mp3
  • .wav
  • .3gp
  • .mp4
  • .mpg, .mpeg
  • .avi
  • .pdf
  • .vcf, .vcard
  • .cal
Max Size limit is 1500KB
Tracking your message delivery
In order to receive updates on the processing of messages in real-time your Application will need to have a publically accessible URL Endpoint that Tall Bob can communicate with.

  • The URL specified must be using HTTPS to ensure that data is sent in a secure format
  • Tall Bob will not send event data to unsecured HTTP endpoints due to the possible presence of PII

Tall Bob tracks a set of events related to the lifecycle of an SMS message which can be sent back to your application.

Typical events that may be received are:
  • Message Sent
  • Message Delivered
  • Message Failed
Example Payload:
{
"eventType": "message_pushed",
"timestamp": 1583377886,
"eventID": "018bfd96-5e8f-11ea-9281-0634275fc628",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-bbe2-029c13ef7f22",
"recipient": "61411118802",
"address": "61411118802",
"status": "ACCEPTED",
"externalID": "AAA-111",
"reference": "BBB-222"
}

You can register to receive even data back in one of two ways
  1. Via the Tall Bob Platform as outlined here
  2. By API request as outlined here
For more information on how to monitor the delivery status of your messages please see here


Contact Synchronisation between Platforms

Your Application
Tall Bob
Credentials for the Tall Bob API must be included with every request, API credentials must be passed in the request header using Basic Auth. Please make sure that the API credentials point to the correct endpoint
API Credentials can be accessed via the Tall Bob Platform, instructions on how to retrieve them are outlined here
Through the use of the Tall Bob API's, you have the ability to:
  • Create Contacts
  • Update Contacts
  • Delete Contacts
For information on how to complete these tasks refer to the documentation here
Tall Bob as a part of integration is generally not considered the 'Source of Truth' when it comes to integration, as such we do not currently emit events for the editing of contact details such as the changing of a first name or the like, it is generally understood these sorts of changes will occur upstream with updates being passed to Tall Bob, one exception to this is Opt-Out status (where tall bob opt-out process is in use)
Tall Bob has the ability to manage opt-outs for contacts, if your application provides the ability for contacts to manage their opt out status for instance through a preference center then it is important that you implement the relevant API calls to manage the status of opt-outs with Tall Bob as outlined here

It is important that Tall Bob is kept updated with the current status of opt-out for all contacts if they are being managed externally, Opt Outs collected and managed by Tall Bob will be stored and maintained within the system, any requests from your application to send to an opted out contact will return an error message normally in the form of
{
"message": "recipient opted out",
"code": 9998
}

With a HTTP Status 400




If you want to receive updates on the opt-out status of contacts you can do so by registering for the following Contact Opted Out event a typical payload, in this case, would look like this:
{
"eventType": "unsubscribe",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"timestamp": 1583338255,
"eventID": "af1267ae-daa9-9ef7-badd-029e1ef618c2",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-9ef7-029c13ef7f22",
"externalID": null,
"videoID": "5f222850-6fa1-11e9-8252-0617db59baea",
"videoName": "asteroid",
"formID": "af1267ae-a6b9-11e9-a4fe-0227e6a58070",
"formName": "thing that we need",
"recipient": "61412345678"
"address": "61412345678"
}




Sending a message with an Engagement Landing Page

Your Application
Tall Bob
Credentials for the Tall Bob API must be included with every request, API credentials must be passed in the request header using Basic Auth. Please make sure that the API credentials point to the correct endpoint
API Credentials can be accessed via the Tall Bob Platform, instructions on how to retrieve them are outlined here
Your application can send SMS messages which include personalised landing pages with engagement content on them,

End Point: Reference Documentation
URL: https://api.tallbob.com/v2/campaigns/send_via_mobile

Example Request Headers:
Content-Type: application/json
Authorization: Basic NTcwYWU0OWU1ZmZjNjpvd0thVXVhNDYwc###


Example Request Payload:
{
"to": {
"61412345678": {
"first_name": "Sample1",
"external_id": 61412345678
},
"61499000111": {
"first_name": "Sample2",
"external_id": 61499000111
},
"61499000222": {
"first_name": "Sample3",
"external_id": 61499000222
}
},
"from": "TallBob",
"message": "Hi {{ first_name }}, The yacht is on the river {{ campaign_link }}",
"landing_page_id": "<< REPLACE_WITH_LANDING_PAGE_UUID >>"
}

  • Payloads must be well formed and JSON Encoded to be accepted
  • This endpoint can include one or more contacts (up to 1,000) in a single request
  • "to" value must be in E.164 format
  • "landing_page_id" refers to the id found within the Tall Bob Application
Tall Bob will take and process the request doing some basic checks to ensure that the request is well formed, expected response will be one of the below

Example Response

Message Queued for Delivery
{
"sms_id": "fb400640-4966-11ea-a1ab-067453a7f748",
"status": "queued",
"created": "2022-09-07 05:02:03",
"price": 0.24,
"num_segments": 1,
"from": "TallBob",
"recipients": 3,
"message": "Hi {{ name }}, The yacht is on the river {{ campaign_link }}",
"reference": null
}
Tracking your message delivery
In order to receive updates on the processing of messages in real-time your Application will need to have a publically accessible URL Endpoint that Tall Bob can communicate with.

  • The URL specified must be using HTTPS to ensure that data is sent in a secure format
  • Tall Bob will not send event data to unsecured HTTP endpoints due to the possible presence of PII

Tall Bob tracks a set of events related to the lifecycle of an SMS message which can be sent back to your application.

Typical events that may be received are:
  • Message Sent
  • Message Delivered
  • Message Failed
Example Payload:
{
"eventType": "message_pushed",
"timestamp": 1583377886,
"eventID": "018bfd96-5e8f-11ea-9281-0634275fc628",
"campaignID": "ed742e82-5e75-11ea-be99-061c79b2f7ce",
"campaignName": "webhooks",
"contactID": "8d38d7fc-daa9-11e9-bbe2-029c13ef7f22",
"recipient": "61411118802",
"address": "61411118802",
"status": "ACCEPTED",
"externalID": "AAA-111",
"reference": "BBB-222"
}

You can register to receive even data back in one of two ways
  1. Via the Tall Bob Platform as outlined here
  2. By API request as outlined here
For more information on how to monitor the delivery status of your messages please see here
Tracking Link Clicks and other Events
If your application has the ability to store or act upon data from a third party you can register webhooks to receive this data, an example of where this might be used would be sending a discount code to people that submitted a form confirming attendance at an event


Messages that include Engagement Campaigns can send back additional event data such as:
  • Landing Page Viewed
  • Contact clicked a link within a landing page
  • Form Submissions
  • etc
You can see a full outline here


Helpful Stuff

  • Looking for definitions that revolve around Mobile, SMS and Telco Industries, then click here
  • More information on HTTP Status code when handling your integration can be found here
  • More information on the SMS Statuses can be found here

If you ever need further assistance or someone to point you in the right direction you can email the team at support@tallbob.com

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article