Communication callbacks are sent out from the Wiraya platform retroactively several times per minute, and can deliver data for events regarding incoming and outgoing SMSes and phone calls. The receiving endpoint must support HTTPS and TLSv1.2. Self-signed certificates are permitted. Batched requests, basic access authentication, client certificates and customized headers are supported.
Requests can be sent as GET, or as POST with a customized JSON or XML body. Customers may customize the callback contents and URLs to contain any available metric. Some metrics are available only for certain types of communications, while others are generic.
Available metrics:
{TYPE} the type of communication the callback relates to (incoming/outgoing SMS/call)
{ID} unique ID for the SMS/call
{CID} unique customer ID the callback is serving
{RID} unique ID of the recipient, if the communication involved a contact list
{PRID} project ID for the SMS or call
{RECIPIENT} the number that received the SMS or call
{SENDER} the sender or caller ID of an outgoing SMS or call
{STATUS} contains the delivery status of an outgoing SMS or call: for outgoing SMSes
the possible values are DELIVERED, NOT_DELIVERED, NOT_WHITELISTED, OPTOUT, FAILURE, UNKNOWN, SPAM and TEST; for outgoing calls they are DELIVERED, NEXTATTEMPT, NOTREACHED, OPTOUT, INCORRECTNUMBER, SPAM, and TEST
{CONTENT} the full content of an outgoing SMS, or relevant payload of an incoming SMS
{1} .. {99} for outgoing SMS/call; the recipient's data fields, if the communication involved a contact list
{CAMPAIGN_NAME} for outgoing SMS/call; name of the campaign, if the communication is associated with a campaign
{CALL_LENGTH} for outgoing calls; the duration of the call, if answered
{KEY_CHOICES} for outgoing calls; the series of key choices made by the callee, as CSV
{SMS_PARTS} for outgoing SMS; the number of parts (SMSes) required to send the content
{SENT_UNIXTIME} Unix timestamp for when an outgoing SMS or outgoing call was sent, or when an incoming SMS was received
{SENT_DATETIME} as above, with the format YYYY-MM-DD HH:MM:SS in UTC
{SENT_DATEISO} as above, with ISO 8601 format in UTC
{DONE_UNIXTIME} Unix timestamp for outgoing SMS delivery report, or when the call ended
{DONE_DATETIME} as above, with the format YYYY-MM-DD HH:MM:SS in UTC
{DONE_DATEISO} as above, with ISO 8601 format in UTC
{RECIPIENT_STATUS} for outgoing SMS; possible values are EXISTS, DOESNOTEXIST, UNKNOWN and LANDLINENUMBER, reflecting the status of the receiving number, either through estimation or by operator confirmation (depending on the customer's account level)
{BULK} the full content of an incoming SMS
{IDENTIFIER} the identifier of an incoming SMS
{PREFIX} the prefix of an incoming SMS
Example URL using GET to transport metrics:
https://infra.company.org/receiver?contact={RID}&id={ID}&to={RECIPIENT}&status={STATUS}
POST example using JSON to transport metrics:
{"id":{ID},"UUID":"{3}","unixtime":{DONE_UNIXTIME},"recipient status":"{RECIPIENT_STATUS}"}
Batched requests are supported when using POST, and the maximum number of items per request is configurable. Batched requests will always contain an array named batch holding up to the configured maximum number of items.
Example POST body:
{"id":{ID},"to":"{RECIPIENT}","when":"{SENT_DATEISO}"}
Resulting POST payload with a batch size of 3:
{
"batch":
[
{
"id":1000007,
"to":"46710000123",
"when":"2019-01-10T13:00:00Z"
},
{
"id":1000088,
"to":"46710000456",
"when":"2019-01-10T13:00:04Z"
},
{
"id":1000105,
"to":"46710000789",
"when":"2019-01-10T13:00:11Z"
}
]
}
Customers are recommended to include the ID of the communication item in their callback setups for referring back to Wiraya in case of problems with the requests or the data. Additionally, we recommend transporting metrics by POST instead of GET to avoid potentially sensitive information ending up in unforeseen locations, e.g. in web server access logs.
Our IP addresses callback requests may originate from (for whitelisting):
35.158.187.151
52.59.121.86
18.197.103.66