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 of the message to send, the formatting of which is dependent on the Type being targeted.
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. This 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 associated 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: 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¶

{
</strong>    "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 associated 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.