© 2018 - Talkip tecnologia
© Todos os direitos reservados
Entenda como funciona a integração com a API de SMS
Every request of the API must have a basic authentication header included, it requires the user and password joined by ‘:’ (colon) encoded in base64, as the example below using ‘user’ and ‘password’ as the credentials:
Authorization: Basic dXNlcjpwYXNzd29yZA==
Alongside the authentication two other headers are required:
Content-Type and Accept, whose values must be application/json as the example below:
Content-Type: application/json
Accept: application/json
To send a SMS, perform a POST request to “http://142.93.78.16/api/sms” sending a json with the following structure:
- {
- “phone” : “11111111111”,
- “message” : “Mensagem de teste!”,
- “callback”: “http://yourcallbackurl”,
- “costCenter”: 1
- }
- phone: the recipient's phone number, in the format DDD+NUMBER (mandatory)
- message: message to be sent (mandatory)
- costCenter: The targeted cost center (optional)
- callback: URL to perform a callback when the status of the SMS changes. (optional)
When performing the request some rules must be considered:
The return of a successful request is as it follows:
- {
- “id”: 4554,
- “phone” : “11111111111”,
- “status” : 200
- “parts”: 2,
- “links”: 3,
- “charged”: 1.223,
- “sentAt”: “2001-06-04 13:05:01”,
- }
- id: generated id of the SMS sent
- phone: destination phone
- status: status of the SMS
- parts: number of parts the message
- links: quantity of links found in the message
- charged: fare charged of the SMS
- sentAt: date and time of the request
✓ The message will be automatically splited if the number of characters exceed 160 characters and each part will count on parts.
| Code | Text of the code | Description |
|---|---|---|
| 200 | OK | Successful request |
| 402 | Payment Required | There is no balance on the account |
| 422 | Unprocessable Entity | Malformed request, missing fields |
| 500 | Internal error | Internal error on the platform |
If the callback field is filled the API will make a GET request to passing information about the status
- {yourcallbackurl}?id=413554&status=2&response=The%20message
- Id: id of the message
- status: status of the SMS in that time
- response: the SMS response
✓ If your callback already have parameters the API parameters will be concatenated at the end of the URL.
| Status | Description |
|---|---|
| 200 | SMS sent |
| 2 | SMS delivered |
| 1 | Processing SMS |
| 3 | Error while sending |
| 7 | No balance in the account |
| 11 | Invalid number |
| 12 | Blocked number |
| 13 | Number in the black list |
| 14 | Message poorly formatted |
To retrieve the current status of the SMS, perform a GET request to “http://142.93.78.16/api/sms/id” replacing the id for the id obtained when the SMS was sent. The response will be like the example below:
- {
- "id": 2,
- "phone": 11111111111,
- "status": 7,
- "parts": 1,
- "links": 1,
- "charged": "1.234",
- "sentAt": "2019-05-31 15:52:10",
- “carrier”: “VIVO”
- “costCenter”: 1,
- “block”: 3
- }
- id: generated id of the SMS sent
- phone: destination phone
- status: status of the SMS
- parts: number of parts the message
- links: quantity of links found in the message
- charged: fare charged of the SMS
- sentAt: date and time of the request
- carrier: carrier of the destiny phone
- costCenter: the cost center used by the SMS.
✓ The costCenter will only appear if is not the default.
✓ The block will be present only if the sms belongs to a block.
The get the responses perform a GET request to “http://142.93.78.16/api/sms/id/responses” replacing the id by the id of the SMS. The response is like the example:
- [
- {
- "content": "This is a response example!",
- "receivedAt": "2019-05-31 17:44:37"
- },
- {
- "content": “ This is the second response example! “,
- "receivedAt": "2019-05-31 17:44:39"
- },
- ]
- content: content of the response
- receivedAt: date and time in which the response was received
To send an SMS block, perform a POST request to “http://142.93.78.16/api/blocks” sending a json with the following structure:
- {
- “message” : “Mensagem para um envoi em massa”,
- “scheduledAt” : “2019-06-04 22:48:00”,
- “callback” : “http://yourcallbackurl”,
“block”:
- [
- {
- “phone”: “11111111111”
- },
- {
- “phone”: “22222222222”
- }
- ]
- }
- message: message to be sent (mandatory)
- scheduledAt: Schedule date and time in which the block will be sent (optional)
- costCenter: The targeted cost center (optional)
- callback: URL to perform a callback when the status of the SMS changes. (optional)
- block: Array of destination phones (mandatory)
- phone: The destination phone
When performing the request some rules must be considered:
Is also possible to specify messages and callbacks for each block destination, like the following:
- {
- “scheduledAt” : “2019-06-04 22:48:00”,
- “costCenter” : 1,
- “block”:
- [
- {
- “phone”: “11111111111”
- “message”: “Mensagem para um envio em massa”,
- “callback”: “http://yourcallbackurl1”
- },
- {
- “phone”: “22222222222”
- “callback”: “http://yourcallbackurl2”
- }
- ]
- }
When performing this type of request some rules must be considered:
The response of a successful request is like the following:
- {
- "id": 4554,
- "quantity”: “3”,
- "parts": 2,
- "links": 3,
- "charged": 1.234,
- "scheduledAt": 2001-06-04 13:05:01
- }
- id: generated id of the block sent
- quantity: quantity of destination numbers
- parts: number of parts the message
- links: quantity of links found in the message
- charged: fare charged of the SMS
- scheduledAt: in case of scheduleAt filled, the date and hour of the schedule
To retrieve the current status of the block and each of its numbers, perform a GET request to “http://142.93.78.16/api/blocks/id” replacing the id for the id obtained when the block was sent. The response will be like the example:
- {
- "id": 2,
- "quantity": 3,
- "parts": 7,
- “links”: 0,
- “charged”: 1.234,
- “sentAt”: “2019-06-04 22:48:04”,
- “numbers”: [
- {
- "id": 32,
- "phone": 11111111111,
- "status": 2,
- "parts": 1,
- "links": 0,
- "charged": "1.234",
- "sentAt": "2019-06-04 22:48:07",
- costCenter”: 1,
- “carrier”: “VIVO”
- },
- {
- "id": 33,
- "phone": 2222222222,
- "status": 22,
- "parts": 1,
- "links": 0,
- "charged": "1.234",
- "sentAt": "2019-06-04 22:48:07",
- costCenter”: 1,
- "carrier": "CLARO"
- }
- ]
- }
- id: generated id of the block sent
- quantity: quantity of destination numbers
- parts: number of parts the message
- links: quantity of links found in the message
- charged: fare charged of the SMS
- sentAt: date and time of the request
- costCenter: the cost center used by the block. Only appears if is not default.
- numbers: array of numbers showing each status of each number, in which the description of fields of are the same of “Getting SMS status” section.
✓ The messages can presented in the block lever or the block’s numbers level. Depends on how the block was sent, on each number or the whole block. The same rules apply to the callback.
To delete a scheduled block, perform a DELETE request to “http://142.93.78.16/api/blocks/id” replacing the id for the id obtained when the block was sent. The response will be like the example:
- {
- "id": 16,
- "quantiy": 2,
- "parts": 2,
- "links": 0,
- "scheduledAt": "2019-06-04 23:30:00"
- }
- id: generated id of the block sent
- quantity: quantity of destination numbers
- parts: number of parts the message
- links: quantity of links found in the message
- costCenter: the cost center used by the block. Only appears if is not default.
- scheduledAt: in case of scheduleAt filled, the date and hour of the schedule