CallFire Solutions

Send Text

Follow

SEND TEXT

Text Messaging allows companies to send out promotional messages, notifications and updates to their users instantly. CallFire enables organizations to send bulk, but personalized, text messages (a.k.a., SMS) to their customers.

There are two mandatory parameters when sending a text message: - To: the phone number to send the message to. As the API allows submitting the message to many recipients at once, this is an array, e.g., To = array('13105551212', '18185551212'). - Message: the text message itself. In general, the message is limited to 160 characters. If necessary this can be changed with optional parameters (see below).

The SendText method returns a broadcastId . This returned broadcastId can also be passed to QueryTexts to be able to track the results of text messages in other activities, such as a campaign, or it can be passed to GetBroadcastStats to get more information.

Request Parameters

ParameterDemo ValueDescriptionData Type
SendText   Data (To and Message) needed to start a text campaign object
RequestId Unique ID, used to de-dup requests and make sure request is not processed twice anyURI
Type Type of Broadcast[VOICE, IVR, TEXT] BroadcastType
BroadcastName Title of Broadcast (default: API Send) string
To List of E.164 11 digit numbers space or comma separated List[PhoneNumber]
ScrubBroadcastDuplicates Scrub duplicates (default: false) boolean
TextBroadcastConfig   Configuration needed for a Text Broadcast object
id Unique ID of BroadcastConfig long
Created DateTime Broadcast was created 'CCYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm]' dateTime
FromNumber E.164 11 digit number or short code PhoneNumber
LocalTimeZoneRestriction   Restrict the times your campaign can run object
BeginTime Earliest time a client can be contacted in the timezone associated with the number's NPA/NXX time
EndTime Latest time a client can be contacted in the timezone associated with the number's NPA/NXX time
RetryConfig   Retry logic for broadcast object
MaxAttempts Max attempts to retry broadcast (default: 1) int
MinutesBetweenAttempts Minutes between broadcast attempts (default: 60) int
RetryResults Conditions to retry on[SENT, RECEIVED, DNT, TOO_BIG, INTERNAL_ERROR, CARRIER_ERROR, CARRIER_TEMP_ERROR, SD, POSTPONED] List[Result]
RetryPhoneTypes Phone types to call in retry[FIRST_NUMBER, HOME_PHONE, WORK_PHONE, MOBILE_PHONE] List[RetryPhoneType]
Message 160 char or less message to be sent in text broadcast. Use rented 'keyword' in message if need response string
BigMessageStrategy Set strategy if message is over 160 chars (default: SEND_MULTIPLE)[SEND_MULTIPLE, DO_NOT_SEND, TRIM] BigMessageStrategy
BroadcastId BroadcastId to send message from long
UseDefaultBroadcast If true send text through existing default broadcast (default: false) boolean
  • indicates choice value, bolded parameters are required

Response Parameters

Message sent successfully:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:Id>1876425001</r:Id>

<r:Location>https://www.callfire.com/api/1.1/rest/broadcast/1876425001</r:Location>

</r:ResourceReference>

No contact or Invalid number:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:HttpStatus>400</r:HttpStatus>

    <r:Message>NO_CONTACTS</r:Message>

</r:ResourceException>

Check the number which will receive the message.

User not logged in or the authentication is wrong:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:HttpStatus>403</r:HttpStatus>

    <r:Message>Authenticated user lacks API privileges</r:Message>

</r:ResourceException>

Check if you are logged in correctly.

Suspended account:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceException xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:HttpStatus>400</r:HttpStatus>

    <r:Message>account suspended</r:Message>

</r:ResourceException>

Contact CallFire's support to solve your account issue. Status 400 is used in other cases too, for example when you write a string in a "date" field. You will receive the details on the "Message" of the Response.

Example: Send Message to Numbers

To get started, here's a simple example of how to send a message to a couple of numbers, setting the receptors ("To", {Number}) and the Message, ("Message", {Text}).


using RestSharp;

namespace [your-namespace]
{
    public class [your-class]
    {
        public string SendText()
        {
            var client = new RestClient("https://www.callfire.com/api/1.1/rest/");
            client.Authenticator = new HttpBasicAuthenticator("YourLoginId", "password");

            var request = new RestRequest("text", Method.POST);
            request.AddParameter("Type", "TEXT");
            request.AddParameter("To", "13105551212");
            request.AddParameter("Message", "Hello, just testing SMS messaging");

            var response = client.Execute(request);
            string content = response.Content;
            return content;
        }
    }
}

Notice the method returns a broadcastId. It can be used with other methods to get status or other information about the broadcast.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

   <r:Id>1876425001</r:Id>

<r:Location>https://www.callfire.com/api/1.1/rest/broadcast/1876425001</r:Location>

</r:ResourceReference>

Example: Add FromNumber and LocalTimeZoneRestriction to a Request

In this example we set the Start and End times that the Broadcast will be operational (i.e., "LocalRestrictBegin" and "LocalRestrictEnd").


using RestSharp;

namespace [your-namespace]
{
    public class [your-class]
    {
        public string SendText()
        {
            var client = new RestClient("https://www.callfire.com/api/1.1/rest/");
            client.Authenticator = new HttpBasicAuthenticator("YourLoginId", "password");

            var request = new RestRequest("text", Method.POST);
            request.AddParameter("Type", "TEXT");
            request.AddParameter("To", "13105551212");
            request.AddParameter("From", "16985552112");
            request.AddParameter("Message", "Hello, just testing SMS messaging");
            request.AddParameter("LocalRestrictBegin", "09:00:00");
            request.AddParameter("LocalRestrictEnd", "17:00:00");

            var response = client.Execute(request);
            string content = response.Content;
            return content;
        }
    }
}

The XML returned is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:Id>1876425002</r:Id>

<r:Location>https://www.callfire.com/api/1.1/rest/broadcast/1876425001</r:Location>

</r:ResourceReference>

Example: Send a text message with a Keyword that Recipients can reply to

In this code snippet, we configure the Number which will be used ("Number", {Phone-Number}), then set the Keyword and the Match. And finally set the message that will be used for the automatic reply. Note that a keyword needs to be purchased before an auto reply can be created.


using RestSharp;

namespace [your-namespace]
{
    public class [your-class]
    {
        public string CreateAutoReply()
        {
            var client = new RestClient("https://www.callfire.com/api/1.1/rest/");
            client.Authenticator = new HttpBasicAuthenticator("YourLoginId", "password");

            var request = new RestRequest("text/auto-reply", Method.POST);
            request.AddParameter("Number", "18185551212"); 
            request.AddParameter("Keyword", "CHOCOLATE"); 
            request.AddParameter("Match", "WHITE"); 
            request.AddParameter("Message", "Thank you for answer, you chose the white chocolate"); 

            var response = client.Execute(request);
            string content = response.Content;
            return content;
        }
    }
}

The XML returned is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:Id>1876225005</r:Id>

<r:Location>https://www.callfire.com/api/1.1/rest/broadcast/1876225005</r:Location>

</r:ResourceReference>

Example: Send Text Message with More than 160 Characters

In this code example, a message longer than 160 characters is configured so that it can be properly handled using the BigMessageStrategy ("BigMessageStrategy", {Behavior}). In this case, we show a "TRIM" option. The other options are to divide the message into more than one and send each of them separately, or abort sending.


using RestSharp;

namespace [your-namespace]
{
    public class [your-class]
    {
        public string SendText()
        {
            var client = new RestClient("https://www.callfire.com/api/1.1/rest/");
            client.Authenticator = new HttpBasicAuthenticator("YourLoginId", "password");

            var request = new RestRequest("text", Method.POST);
            request.AddParameter("Type", "TEXT");
            request.AddParameter("To", "13105551212");
            request.AddParameter("Message", "Hello, testing SMS messaging which is over 160 chars");
            // Insert a text message which is over 160 chars
            request.AddParameter("BigMessageStrategy", "SEND_MULTIPLE");
            // Set strategy if message is over 160 chars 

            var response = client.Execute(request);
            string content = response.Content;
            return content;
        }
    }
}

The XML returned is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:Id>1876425004</r:Id>

<r:Location>https://www.callfire.com/api/1.1/rest/broadcast/1876425001</r:Location>

</r:ResourceReference>

Example: Send a Personalized Text Message to Each Recipient

In this example, a simple message is configured, with the difference that the message will contain the name of each contact, by virtue of the variable added to it (i.e., ${contact.firstName} and ${contact.lastName}).

 

using RestSharp;

namespace [your-namespace]
{
    public class [your-class]
    {

        // Simple example
        public string PersonalizedMessage()
        {
            var client = new RestClient("https://www.callfire.com/api/1.1/rest/");
            client.Authenticator = new HttpBasicAuthenticator("YourLoginId", "password");

            var request = new RestRequest("broadcast", Method.POST);
            request.AddParameter("Name", "Example personalized TextBroadcast");
            request.AddParameter("Type", "TEXT");
            request.AddParameter("Message", "Hello ${contact.firstName}, please confirm that your home phone is the following: ${contact.homePhone}");
            request.AddParameter("ScrubBroadcastDuplicates", "true");
            
            var response = client.Execute(request);
            string content = response.Content;
            return content;
        }
    }
}

The XML returned is:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<r:ResourceReference xmlns="http://api.callfire.com/data" xmlns:r="http://api.callfire.com/resource">

    <r:Id>1876425005</r:Id>

<r:Location>https://www.callfire.com/api/1.1/rest/broadcast/1876425004</r:Location>

</r:ResourceReference>

 

In this case a contact batch has to be created for the the broadcast created previously. Thus, the variables used on the message will take the information from the contacts added on the contact batch. (See the BROADCAST-CREATECONTACTBATCH document)

Have more questions? Submit a request

Comments