Send and Receive an SMS with a Custom Sender ID

from __future__ import print_function
from telesign.messaging import MessagingClient

customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "Your test phone number with no special characters or spaces."
message = "You're scheduled for a dentist appointment at 2:30PM."
message_type = "ARN"

messaging = MessagingClient(customer_id, api_key)
response = messaging.message(phone_number, message, message_type, sender_id="Phone number you purchased from TeleSign goes here.")

This Quick Start describes how to send an SMS to an end user with a custom sender ID. A sender ID is sometimes referred to as a dedicated phone number. It is the number your end user sees when they receive a message from you. They can also use this number to respond to with a message.

You can use the SMS API to send alerts, reminders, and notifications for a variety of situations such as:

  • Weather updates
  • Status of a package being delivered
  • Reminder for appointments or events
  • A notification about a special offer or promotion
  • Notifications about a change in status to an account, for example to let someone know their password changed

This Quick Start includes the following sections:

Requirements

For this quick start, the following is required:

  • customer ID - obtain from your account by logging in to portal.telesign.com
  • API key - obtain from your account by logging in to portal.telesign.com
  • SDK - Access to TeleSign’s GitHub repository (you must request access from your Technical Account Manager for the SDK, or the links will not work):
  • Python
  • Ruby
  • PHP
  • C#
  • Language Version
  • Python - 2.7+
  • Ruby - 2+
  • PHP - 5.6+
  • C# - 4.5

Install the SDK

  1. Obtain your customer ID and API key.
  2. Log in to GitHub and get the SDK:
  1. Download or clone the repository. If you download it, extract the repository from the .ZIP file.
  2. To install the SDK for use, do the following:
From a terminal run:

pip install telesign

Buy a Phone Number

TeleSign offers the option of buying a sender ID to use to send messages to your end users. A sender ID is sometimes referred to as a dedicated phone number, and in the portal (portal.telesign.com) it is referred to as a phone number. A TeleSign phone number is required to use Inbound SMS. To buy a phone number to use as a sender ID, do the following:

  1. Go to portal.telesign.com and log in.
  2. If you are on TeleSign’s free trial, you need to upgrade and provide billing information before proceeding. You do that by clicking the Upgrade button in the upper lefthand corner. If you already upgraded your account, ignore this step.
  3. In the left nav, under Products, click SMS.
  4. Click Settings.
  5. Next to Customer Callback URLs, click Edit. The Customer Callback URLs popup appears.
  6. Click Add a URL.
  7. Enter the URL you want to use for receiving callbacks from your end users.
  8. Click Save.
  9. On the left nav, under Account, click Phone Numbers. The Buy a Phone Number screen appears.
  10. You can search for a phone number to use as a sender ID by country and by feature using the drop downs. Use the Search by Country drop down to choose the appropriate country. Because you are going to use the phone number as a sender ID, open the Feature drop down and choose 2-Way SMS.
  11. Click Search.
  12. From the list of numbers returned, choose a number you want to buy and next to it click Buy Now. If you did not set up a callback URL, you will not be able to buy a number. You must have your URL configured before buying. If your URL is configured, the Confirm Payment popup appears.
  13. Check to see that you have the correct phone number and features. Review the compliance information provided if you need to. If everything looks ok, click Submit. You get a message saying your phone number was successfully purchased.

Enable Inbound SMS and Status Callbacks

Inbound SMS and status callbacks are automatically enabled for you in the portal when you buy a phone number. You can read more about Inbound SMS here: Inbound SMS.

You will also need to provide a callback URL. The callback URL points to a server you configure that handles incoming responses. For example, your callback URL might point to a server with a database that stores all end user responses. The response is in JSON, and looks like this:

{
  "status": {
    "updated_on": "2017-01-27T19:46:55.787464Z",
    "code": 1500,
    "description": "Delivered to customer"
  },
  "submit_timestamp": "2017-01-27T19:46:55.778000Z",
  "errors": [],
  "user_response": {
    "phone_number": "13392273726",
    "sender_id": "222222",
    "mo_message": "MO message content."
  },
  "sub_resource": "mo_sms",
  "reference_id": "0143D53D86A2030BE20025B600000002"
}

You can read more about each parameter in this response on the Inbound SMS page.

Set Your Sender ID and Send an SMS Message

This section explains how to send an SMS message with a custom sender ID using the SMS API for Enterprise. The sample code provided earlier is broken out into pieces and explained below.

In this code sample, you provide your customer ID and API key to authenticate yourself with TeleSign. Then you create a MessagingClient object and use the message method to send an SMS containing the message you specify with the message type and sender ID you specify. The steps below explain the code sample with more detail.

  1. Begin by adding statements for including the appropriate part of the TeleSign SDK and any additional language specific functions you may need.
from __future__ import print_function
from telesign.messaging import MessagingClient

#If you are working with a version of Python 3, you do not need the first import #statement (`from __future__ import print_function`).
  1. Insert values for each of the items from customer_id through to message_type.
  • customer_id- Your TeleSign assigned customer ID, available in your account information in the portal.
  • api_key /apiKey - Your TeleSign assigned API key, available in your account information in the portal.
  • phone_number / phoneNumber - The phone number you want to use for the example. If you are doing a free trial, the phone number must be verified (verifying the number is not required if you are a paying customer). When you provide the number, it should be a string with no spaces or special characters. Include the complete number. For example, if you are doing a phone number for America, you would include the country code and the area code with the number. For example 16505551212.
  • message - Provide your message as a string.
  • message_type / messageType - Label the type of message you are sending. You have three choices: OTP - One time passwords, ARN - Alerts, reminders, and notifications, and MKT - Marketing traffic.
customer_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
api_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="

phone_number = "The phone number you want to send an SMS to goes here."
message = "You're scheduled for a dentist appointment at 2:30PM."
message_type = "ARN"
  1. Instantiate a MessagingClient object containing your customer ID and API key. Send an SMS to the phone number containing the message, message type, and add the sender ID. Store the response in response or for C#, in telesignResponse.
messaging = MessagingClient(customer_id, api_key)
response = messaging.message(phone_number, message, message_type, sender_id="Your sender ID goes here.")
  1. You should receive an SMS message containing the message you specified at the phone number you specified, from the sender ID you specified. Please note that sometimes you will not see the sender ID you specified due to how TeleSign and different providers handle custom sender IDs. You can examine the result of your phone call by looking at the contents of ‘response’.

Code it Without the SDK

TeleSign’s SDKs make implementation a lot easier because authentication is handled for you. If you want to write all your own code, you must handle authentication yourself. You’ll need the following documents: