Messaging

The Message API's allow you to send messages (SMS, WhatsApp, etc.) across a global network with the addition of supporting methods for lookup and validation of mobile numbers.

Sending a Message

Send a message anywhere in the world.

URL: base/Message/Send
Method: POST
{
  "Source": "12345678901",
  "Destination": "12345678901",
  "Message": "message",
  "Reply": true,
  "When": "2020-02-04T11:47:33.645773+00:00",
  "Window": [{ "From": "09:00", "To": "16:00", "Days": "1,2,3,4,5"}],
  "Callback": "https://yourco.com/api/messagetracker",
  "Lookup": true,
  "Test": false,
  "Timeout": "4320",
  ”Type”: 0,
  "MetaData": 
    [
        { "RequestID": "1234567890DEFED" },
        { "OrgID": 1010 },
        { "Instance": "ETRERT"},
        { "Campaign": 1242 },
        { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
    ]
}

Parameters

Name	Type	Description
Source	Mandatory	The source of the message. This can be a short code, a long number or a branded value up to 11 characters long.
Destination	Mandatory	The destination of the message. This must be the full number prefixed with the country code and no leading zeros. This controls the destination of the message and helps with Windows.
Message	Mandatory	The text message to send. This can be up to 2000 characters long.
Reply	Optional (Default: false)	A boolean value indicating whether the message can be replied to or not. If this is true then the source may be replaced depending on destination value and the route the message has to take to get to its destination. Importantly, this flag allows you to get a reply through an appropriately configured web hook or callback.
When	Optional (Default: now)	A date and time indicating when the message should be sent. This allows the opportunity to submit a message to be sent at a later date.
Window	Optional (Default: any time)	An array of time windows that the message can be sent. The allows you to specify different time windows as to when the message can be sent. Each window follows these rules.
Callback	Optional (Default: Account Settings)	There is the ability to override the standard callback method associate with your account. For more information on callbacks check here.
Lookup	Optional (Default: false)	A boolean value indicating whether a lookup on the destination number should be carried out before it is sent to see whether the number is a landline or mobile. If the number is a landline it will not be sent. This combines the lookup method and the send into one process for you.
Test	Optional (Default: false)	A boolean value that indicates whether the message should be sent or not. If set to true the message will not be sent, but the internal DIY Surveys Routing will be tested.
Timeout	Options (Default: 4320)	a numeric value defining the number of minutes the DIY Surveys Platform will maintain a message to be replied to. The default is 3 days.
MetaData	Optional	For more information on metadata check here.
Macros	Optional	A set of values to use as insert references for macros. For more information on this please check here.
Type	Optional (Default: 0)	A numeric value indicating the type of message: 1. 0 = Sms, 1 = WhatsApp, 2 = Facebook, 3 = WhatsAppTemplate. For more information please check here.

Returns

{
    "MessageID": "MS1312312312323",
    "Status": "sent",
    "Carrier": "EE",
    "Reachable": true,
    "NumberType": "Mobile"
}

Return Values

Name	Description
MessageID	The DIY Surveys Message ID available for you to track the message in other methods and callbacks.
Status	The initial status of the send. This can be any one of the following values.

If a lookup is performed as part of the process the following return values will be included:

Name	Description
Carrier	The name of the carrier. This can be any valid string or the word Unknown
Reachable	A boolean value indicating whether the number is reachable.
NumberType	A string indicating the type of number - Mobile, Landline or Unknown

HTTP Statuses

In addition to the standard responses the following HTTP statuses can be returned:

Status	Description
400	The destination number is invalid
400	The destination and source cannot be the same
400	The message length must be greater than zero
400	There was a problem sending the message. Please refer to the status

Sending Messages without a Callback

If you send a message without a call back, there some additional responses that you can get along with an HTTP Status of 400:

Landline detected

{
    "MessageID": "Unknown",
    "Status": "Reachable",
    "Carrier": "EE",
    "Reachable": true,
    "NumberType": "Landline"
}

Blocked number

{
    "MessageID": "Unknown",
    "Status": "Blocked",
    "Carrier": "EE",
    "Reachable": false,
    "NumberType": "Mobile"
}

Kill

Kill off any outstanding activity with one or some messages, by providing an array or information.

URL: base/Message/Kill
Method: DELETE
{
  [
    {
      "Destination": "12345678901",
      "MetaData": 
      [
        { "RequestID": "1234567890DEFED" },
        { "OrgID": 1010 },
        { "Instance": "ETRERT"},
        { "Campaign": 1242 },
        { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
      ],
      "Callback": "https://yourco.com/api/messagetracker",
    },
    ....
  ]
}

Parameters

Name	Type	Description
Destination	Mandatory	The destination of the message. This must be the full number prefixed with the country code and no leading zeros.
Callback	Optional (Default: Account Settings)	There is the ability to override the standard callback method associate with your account. For more information on callbacks check here.
MetaData	Optional	For more information on metadata check here.

Returns

Nothing

Lookup

Lookup a number on the network to see whether it is reachable and whether it is a mobile number.

URL: base/Message/Lookup
Method: POST
{
  "Number": "12345678901",
  "MetaData": 
    [
        { "RequestID": "1234567890DEFED" },
        { "OrgID": 1010 },
        { "Instance": "ETRERT"},
        { "Campaign": 1242 },
        { "TimeStamp": "2020-02-04T11:47:33.645773+00:00" }
    ]
}

Parameters

Name	Description
Number	The number to lookup
MetaData	Optional	For more information on metadata check here.

Returns

{
  "Number": "01234567890",
  "Carrier": "EE",
  "Message": "Success Message",
  "Reachable": true,
  "Status": "Success",
  "NumberType": "Mobile"
}

Return Parameters

Name	Description
Number	The number that was looked up
Carrier	The name of the carrier. This can be any valid string or the word Unknown
Message	A status message which varies depending on the success of the lookup and the carrier involved.
Reachable	A boolean value indicating whether the number is reachable.
Status	A string indicating the result of the lookup. Either Success or Failure
NumberType	A string indicating the type of number - Mobile, Landline or Unknown

HTTP Statuses

In addition to the standard responses the following HTTP statuses can be returned:

Status	Description
400	There was a problem with the Lookup. Please check your request and try again