Toggle menu

SMS Worker

The SMS worker allows iCM to interact with an SMS provider, generating message content in iCM and passing it to the provider to be sent.

The SMS worker can integrate with a range of providers. The exact configuration of these providers will vary, and they must exist as JavaScript files in the API Server's SMS worker providers directory.

Worker Configuration Properties

PropertyTypeDescription
providersArray, requiredThis is an array of the provider names that represents the providers that can be specified in the sendSMS function. Implementations must exist for all of the providers
defaultProviderString, requiredThis is the name of the provider that will be used if none is specified
providersDirString, requiredThis is the directory in which provider implementations can be found. Its default value is within the worker distribution and should not be changed

The following optional properties can be set if you are using an End Point as a provider:

PropertyTypeDescription
EndPoint_ApiClientConfigObjectIf you are using the End Point provider you can provide an apiclient configuration object (to set an apiKey, serverid, user/password etc if needed)
EndPoint_NameStringIf you are using the default End Point provider, this is the name of the End Point that will be called by it
EndPoint_WorkerStringEither ajaxlibrary or serverlibrary, depending upon where your End Point is deployed
EndPointsArrayAn array of End Point provider details. The properties set for each provider override those defined above
EndPoints.ProviderStringThe name of this provider that should be set in the sendSMS method call
EndPoints.EndPoint_NameStringThe name of the End Point that will be invoked when this provider is used
EndPoints.EndPoint_WorkerStringThe worker this End Point is deployed to
EndPoints.ApiClientConfigObjectAny configuration to supply to the End Point

Other providers may require additional configuration information, for example an API key, supplied as part of the worker configuration. These configuration settings should be named with the provider name as a prefix. For example, the Eagle Eye provider requires a username, password and sender:

"EagleEye_username": "xxxxxx",
"EagleEye_password": "xxxxxx",
"EagleEye_sender": "xxxxxx"

Example

{
    "name": "sms",
    "instances": 1,
    "defaultProvider": "Example",
    "providers": ["Example", "EndPoint"],
    "EndPoint_Name": "Tests.smsHandler",
    "EndPoint_Worker": "serverlibrary",
    "EndPoint_ApiClientConfig": {},
    "EndPoints": [{
        "Provider": "o2",
        "EndPoint_Name": "Tests.smsHandlerO2",
        "EndPoint_Worker": "serverlibrary",
        "EndPoint_ApiClientConfig": {}
    }, {
        "Provider": "ee",
        "EndPoint_Name": "Tests.smsHandlerEE",
        "EndPoint_Worker": "serverlibrary",
        "EndPoint_ApiClientConfig": {}
    }]
}

In the example above, if no provider is supplied with the call to sendSMS, the Example provider will be used.

If the call to sendSMS sets EndPoint as the provider, the Tests.smsHandler End Point will be used.

To use the Tests.smsHandlerO2 End Point, set the provider as o2.

API

The functions and responses of the SMS worker will vary between providers. By convention all support sendSMS.

sendSMS

The send SMS function is used to send message details to your chosen provider.

ParameterTypeDescription
providerString, optionalThe provider you would like to pass the message to. The defaultProvider will be used if none is specified
destNumberString, requiredThe number to send the SMS to
messageString, requiredThe SMS message
senderString, optionalA sender identifier

Example Request

In this example the default "Example" provider will be used.

let resp  =  this.callWorkerMethod( "sms",  "sendSMS",   { 
    "destNumber" :  params.mobileNumber,
    "message" :  params.message 
});

Example Responses

Responses will vary by provider. By convention the result object should contain the following.

PropertyTypeDescription
sentBooleanWhether or not the SMS was sent
providerRespObjectThe actual response from the SMS provider
errorStringIf an error is returned from the provider the error text will be in this property

The "Example" provider always returns "sent": true.

{
    "jsonrpc": "2.0",
    "id": 9,
    "result": {
        "sent": true,
        "providerResp": {
            "resp": "No message actually sent"
        }
    }
}

listProviders

Lists all currently configured providers and returns information about them.

let resp = this.callWorkerMethod("sms", "listProviders", {});
return resp;

Each provider implements an "information" function which provides the detail of the response.

{
    "jsonrpc": "2.0",
    "id": 11,
    "result": [{
        "name": "Example",
        "description": "Example implementation.",
        "restrictions": "Does not actually send a message.",
        "chargeable": false,
        "providerWebsite": ""
    }]
}

Last modified on August 03, 2023

Share this page

Facebook icon Twitter icon email icon

Print

print icon