SMS Connector

Vtiger has an SMS Messages module that supports different SMS providers which will help in sending text messages from CRM. Right now, it is limited to some providers like Twilio, ClickATell, IndiaSms, Gupshup etc. But, we have a lot more SMS providers which are not yet available in Vtiger. SMS Connectors helps you enable any customer provider we want. With a simple xml code we can introduce a new SMS Provider in the SMS Messages module.

Build your own

Let's dig in to know how to enable the SMS Connector for the provider you like.

Navigate to Menu > Platform > Module Designer

Click Add New Module on the top right corner and create an Extension Module. Give a name to the module and ignore selecting an App Category.

VTAP has introduced a new Resource type in Module Designer called Connectors, select Connectors on the right side panel and select SMS in the drop down and giving a name to the connector. For example if you are integrating with Twilio.com service then use Twilio which will appear in the SMS Configuration page when setting it up.

Now you will see an editor where you need to define the SMS connector parameters, headers, end points and configuration parameters. On adding the connector, a default XML template will be loaded which needs to be updated with the provider details which we want to enabled.

4 .Let’s go through each XML component that needs our attention.

Config

This is where we need to update the fields that will be shown in configuration page to connect. This is in Settings > SMS Messages > Provider configuration. We support text, password, url fields in here.

<config>
   <fields>
       <field name="username" label="User Name" type="text" />
       <field name="password" label="Password" type="password" />
       <field name="type" label="Connection Type" type="picklist" />
           <options>
               <option> Type1 </options>
               <option> Type2 </options>     
           </options>
       </field>
    </fields>
</config>

Provider

We should configure SMS provider endpoint and authentication details here. This is what we use for connecting to the SMS provider service to do SMS actions.

Any XML component in the connector will accept values from config fields. We have supported tags to access config fields. For instance if we want to access the username field from config then we can use $config.$fields.username

<provider>
    <url>https://provider_url</url>
    <auth>
        <basic username="$config.$fields.username" password="$config.$fields.password"/>
    </auth>
</provider>

Message_Send

So far we enabled the fields needed and configured the Provider details. Now, it is time to do the action part, configuration that is needed for sending SMS. This has sub components

message_send.request


request.url	sms provider endpoint for sending sms. We can leave this empty if provider url is good enough.
request.header	if provider is expecting any headers while sending sms we can enable those headers from here.
request.parameters	parameters that need to be sent while sending sms. We can use config fields if there are any provider account specific parameters. We will have some dynamic parameters that are controlled from Vtiger UI (message, recipients) for which we can use @message, @recipients.

message_send.response

Response has a format attribute. This helps in identifying the format of response from the SMS provider after sending SMS. For now, we only support xml or json format

We need to configure the identifiers of response. What key should be considered as message id, status etc. We support nested values as well(for ex:- result.content.message_id)


response.messages	If sent message is in any nested property of response then this should be configured. Ignore this, if returned response itself is the details.
response.message_id	this is used to identify message id from response
response.message_status	this is used to identity message status from response
response.error	this is used to identify error if sms is failed

message_send.callback

We can remove this component if provider doesn’t support callback

Some providers support callback. When SMS is sent from the CRM, the provider will keep it in queue, once it is delivered then it hits the callback url

We auto generate callback urls for custom SMS providers. We can use runtime parameter @callback if we want to include in request parameters

Same as response we have format attribute and identifiers for callback.

callback.message_id
callback.message_status

message_send.statuses

Each provider can have their own status values for SMS. We need to configure what status from the response should be used as Processing or Delivered or Failed

This is how message_send going to look after configuring every thing

<message_send>
     <request method="post">
         <url> /send </url>
         <headers>
             <header name="content-type" value="application/json" />
         </headers>
         <parameters>
             <parameter name="From" value="$config.fields.from" />
             <parameter name="To" value="@recipients" />
             <parameter name="Body" value="@message" />
             <parameter name="Callback" value="@callback" />
         </parameters>
     </request>

     <response format="json"> 
         <message_id use="messageId" />
         <message_status use="messageStatus" />
         <message_to use="messageTo" />
         <error_message use="errorMessage" />
     </response>

     <callback format="json">
         <message_id use="messageId" />
         <message_status use="messageStatus" />
     </callback>

     <statuses>
         <status Processing="queued,sending" />
         <status Delivered="delivered" />
         <status Failed="failed" />
     </statuses>
</message_send>

Message_Status

In each SMS notifier record in the CRM we have the option to get status of the message, this part is going to be used for that request. Like, message_send we have request, response, statuses as sub components in this component as well. This is how it is going to look

<message_status>
        <request method="get">
            <url> /@messageid</url>
                   <parameters>
                              <parameter name=”name” value=”value”> </parameter>
                        </parameters>
        </request>

        <response format="json">
            <message_status use="message_state" />
            <message_to use="to_number" />
        </response>

        <statuses>
            <status Processing="queued,sent" />
            <status Delivered="delivered" />
            <status Failed="failed,rejected,undelivered" />
        </statuses>
</message_status>

Once we update the XML with all required details. We are good to go with publishing the connector. Once we Save and Publish the Connector. We can see a new Provider added in SMS Notifier settings (Settings > Extensions > SMS Provider Configuration)

Configure the Provider specific details and activate it.

To test if it's working properly, try sending sms to a Contact. Go to the Contacts module, and select the SMS option. Select the phone number and send sms and see if it works.

Examples

Twilio

<?xml version='1.0'?>
<connector for="SMSNotifier">

   <config>
     <fields>
        <field name="AccountSID" label="Account SID" type="text" required="true">                
              </field>
        <field name="AuthToken" label="Auth Token" type="text" required="true">      
              </field>
        <field name="From" label="From" type="text" required="true"> 
              </field>
     </fields>
   </config>

   <provider>
      <url>      
        https://api.twilio.com/2010-04-01/Accounts/$config.$fields.AccountSID/Messages 
      </url>
      <auth> 
         <basic username="$config.$fields.AccountSID"   
                  password="$config.$fields.AuthToken" />
      </auth>
    </provider>

    <message_send>
        <request method="post">
            <headers> 
                <header name="content-type" value="application/json" />
            </headers>
            <parameters>
                <parameter name="From" value="$config.$fields.From" />
                <parameter name="To" value="@recipients" />
                <parameter name="Body" value="@message" />
                <parameter name="StatusCallback" value="@callback" />
            </parameters>
        </request>

        <response format="xml">
            <message_id use="Message.Sid" />
            <message_status use="Message.Status" />
            <message_to use="Message.To" />
            <error_message use="RestException.Message" />
        </response>

        <callback>
            <message_id use="MessageSid" />
            <message_status use="MessageStatus" />
        </callback>

        <statuses>
            <!-- CONFIGURE : What is the Processing/Delivered/Failed status value -->
            <status Processing="queued,sending" />
            <status Delivered="delivered" />
            <status Failed="failed" />
        </statuses>
    </message_send>

    <message_status>    
        <request method="get">
            <url> /@messageid </url>
        </request>

        <response format="xml">
            <message_id use="Message.Sid" />
            <message_status use="Message.Status" /> 
        </response>

        <statuses>
            <status Processing="queued,sending" />
            <status Delivered="delivered" />
            <status Failed="failed" />
        </statuses>
    </message_status>

</connector>

BulkSMS

<?xml version='1.0'?>
<connector for="SMSNotifier">

    <config>
        <fields>
            <field name="username" label="User Name" type="text" required="true" />
            <field name="password" label="Password" type="password" required="true" /> 
        </fields>
    </config>

    <provider>
        <url> https://api.bulksms.com/v1 </url>
        <auth> 
            <basic username="$config.$fields.username" 
                  password="$config.$fields.password" />
        </auth>
    </provider>

    <message_send>
        <request method="post">
            <url> /messages </url>

            <headers>
                <header name="content-type" value="application/json" />
            </headers>

            <parameters>
                <parameter name="to" value="@recipients" />
                <parameter name="body" value="@message" />
            </parameters>

        </request>

        <response format="json"> 
            <message_id use="id" />
            <message_status use="status.type" />
            <message_to use="to" />
            <error_message use="title" />
        </response>

        <statuses>
            <status Processing="ACCEPTED,SCHEDULED" />
            <status Delivered="DELIVERED" />
            <status Failed="FAILED" />
        </statuses>

    </message_send>

    <message_status>

        <request method="get">
            <url> /messages/@messageid</url>
            <headers>
                <header name="content-type" value="application/json" />
            </headers>
        </request>

        <response format="json">
            <message_status use="status.type" />
        </response>

        <statuses> 
            <status Processing="ACCEPTED,SCHEDULED" />
            <status Delivered="DELIVERED" />
            <status Failed="FAILED" />
        </statuses>

    </message_status>

</connector>

Plivo

<?xml version='1.0'?>
<connector for="SMSNotifier">

    <config>
        <fields>
            <field name="AuthID" label="Auth ID" type="text" required="true"> </field>
            <field name="AuthToken" label="Auth Token" type="text" required="true"> 
                  </field>
            <field name="From" label="From" type="text" required="true"> </field>
        </fields>
    </config>

    <provider>
        <url> https://api.plivo.com/v1/Account/$config.$fields.AuthID/Message/ </url>
        <auth> 
            <basic username="$config.$fields.AuthID" 
                password="$config.$fields.AuthToken" />
        </auth>
    </provider>

    <message_send>
        <request method="post">
            <url> </url>
            <headers>
                <header name="Content-Type" value="application/json"> </header>
            </headers>
            <parameters>
                <parameter name="src" value="$config.$fields.From" />
                <parameter name="dst" value="@recipients" />
                <parameter name="text" value="@message" />
                <parameter name="method" value="POST" />
                <parameter name="url" value="@callback" />
            </parameters>

        </request>

        <response format="json">
            <message_responses use="message_uuid" />
            <error_message use="error" />   
        </response>

        <statuses>
            <status Processing="queued,sent" />
            <status Delivered="delivered" />
            <status Failed="failed,rejected,undelivered" />
        </statuses>

        <callback> 
            <message_id use="MessageUUID" />
            <message_status use="Status" />
        </callback>
    </message_send>

    <message_status>

<request method="get">
            <url> /@messageid</url>
        </request>

        <response format="json">
            <!-- CONFIGURE : What is the status identifier in response -->
            <message_status use="message_state" />
            <message_to use="to_number" />
        </response>

        <statuses>
            <status Processing="queued,sent" />
            <status Delivered="delivered" />
            <status Failed="failed,rejected,undelivered" />
        </statuses>
    </message_status>

</connector>