Intro

This API is meant to send SMSs messages as notifications. This services only works in production environment.

Important Points

Required fields

All the fields in the body are mandatory and kiban cloud performs validations on the information sent to detect special characters or incorrect formats.

Validations

The following validations are applied to the fields in the boody:

countryCode:
- Must have a length less than or equal to 4 characters
- must be a value according to the International Telecommunication Union adding a plus (+) at the beginning. For example, to send an SMS to Mexico, you must send +52 in this field
to:
- Indicate the phone number to which the SMS will be sent.
message:
- Message to send the NIP. You can put any message but we remind you that SMS messages without special characters can have up to 160 characters, including spaces and line breaks. If the message is longer, kiban will split it into several messages and each of these sent messages will be counted as one SMS.

Callback

If you want to receive the different statuses of the SMS sent, you can receive callbacks in your API. To do this, you must add the following headers to the request.

header name	Description
urlCallback	Header to indicate the URL to which we will send the notifications with the response
xApiKeyCallback	Header to assign an API key if you need to add security to your service

Response

You can find an examples of the different kinds of responses in the examples of the call.

Callback responses

If you activated a callback to receive the status of the SMS, you will be able to receive the following statuses:

Pending, when we receive the request and we are generating the sending of the NIP

{
  "event": "PENDING",
  "date": "2024-12-24T20:24:44.689415709Z",
  "linkId": "676b188a6ef8abaf775fef10"
}

Sent, when we send the SMS

{
  "event": "SENT",
  "date": "2024-12-24T20:24:44.71487296Z",
  "linkId": "676b188a6ef8abaf775fef10"
}

Success, when we detect that the client correctly received the SMS.

{
  "event": "SUCCESS",
  "date": "2024-12-24T20:24:46.284059543Z",
  "linkId": "676b188a6ef8abaf775fef10"
}

Error, indicates a generic error when an error occurred when sending the SMS, generally because it is not a correct number, it does not exist or it is not enabled to receive the SMS.

{
  "event": "ERROR",
  "date": "2024-12-24T20:33:48.35163521Z",
  "errorMessage": "The destination number you are trying to reach is unknown and may no longer exist.",
  "linkId": "676b1aa96ef8abaf775fef27"
}