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

• 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).