HTTP API dlr¶
- Table of contents
- HTTP API dlr
Sends Delivery Receipt to a message originator.
Logic of work is following:
1. Server Smartswitch sends a message to a client.
2. Client receives a message. In case if thee message has been successfully handled, client returns message_id to the Smartswitch server.
3. Client send a Delivery Receipt, when the message has been displayed on a terminal of an end user, or when message delivery has failed.
Between 2 and 3 can pass quite a long time interval.
For example, if end user is offline.
In this case client can place the message in a buffer, respond to Smartswitch server, that message has been successfully handled, and wait to end user coming back online during 3 days.
Upon user coming appearing online, client sends to Smartswitch server delivery receipt using this API.
Arguments¶
| argument | mandatory | description |
| _login | yes | coincides with the user / company login to the personal account |
| _password | yes | matches the user / company password to the personal account |
| message_id | yes | ID of a message. It should match with message ID, which has been returned to Smartswitch server upon acceptance of a message by a client |
| message_state | yes | one of: enroute, delivered, expired, undeliverable, accepted, unknown, rejected |
| request_id | no | Value, assigned by client. Will be returned to client in response |
Returned data¶
Server returns response in JSON API format.
Response will contain one of:
- errors.
Array of errors, occured when processing the request. - data.
JSON object, which contains request results, in case if request from client contains 1 number.
Array of JSON objects, in case if request from client contains several numbers.
errors and data will not be present in 1 response simultaneously.
Each response contains either errors, or data.
| attribute | mandatory | description |
| id | yes | response ID assigned by server |
| type | yes | "dlr" |
| request_id | yes, if client has passed request_id inside the request | argument that has been passed by the client |
| attribute | mandatory | description |
| code | yes | Short error code. Can be used by a client for conditional error handling. It doesn't depend on a client's locale. |
| detail | yes | Error details. Can be used by a client to display inside contents of a error dialog. Can be returned by the server in a locale of a client. |
| title | yes | Error title. Can be used by a client to display in the header of the error dialog. Can be returned by the server in a locale of a client. |
Examples¶
Report of a delivery of 1 message¶
| request | POST "https://your.server.name/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&_login=LOGIN&_password=PASSWORD" |
| response |
{
"data" : {
"attributes" : {
"status" : "ok"
},
"id" : "1561370632713",
"meta" : {
"request_id" : "1"
},
"type" : "dlr"
}
}
|
Report of a delivery of 2 messages¶
| request | POST "https://your.server.name/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&message_id=1561370632522&message_state=delivered&request_id=2&_login=LOGIN&_password=PASSWORD" |
| response |
{
"data" : [
{
"attributes" : {
"status" : "ok"
},
"id" : "1561371433517",
"meta" : {
"request_id" : "1"
},
"type" : "dlr"
},
{
"attributes" : {
"status" : "ok"
},
"id" : "1561371433518",
"meta" : {
"request_id" : "2"
},
"type" : "dlr"
}
]
}
|
Error¶
| request | POST "https://your.server.name/api/dlr?message_id=1561370632513&message_state=delivered&request_id=1&_login=LOGIN&_password=PASSWORD" |
| response |
{
"errors" : [
{
"code" : "authentication",
"detail" : "Please check your login and password",
"title" : "Authentication error"
}
]
}
|