SMS API Doc.

SMS API Doc.

Introduction

This API offers services for managing and sending SMS messages, including handling message templates, clients, files, and
subscriptions. It adheres to RESTful principles, supporting Create, Read, Update, and Delete (CRUD) operations. This document
details the available API endpoints, their usage, and provides sample requests and responses.
SMS Developer Module
Base URL
The base URL for all endpoints is: https://bevatel-system-api.bevatel.com/.
Headers
All requests must include the following headers:
json
  1. {
  2. “Authorization”: Bearer YOUR_API_TOKEN,
  3. "Content-Type": "application/json"
  4. }
You can got the Bearer YOUR_API_TOKEN from API module



Send Quick Message
Send a quick message to one or more phone numbers.
Parameters



Notes:
  1. If the user provides a templateMessageId, they should leave the content field empty. Conversely, if the user fills in the content, they can leave the templateMessageId empty.
  2. Ensure that the fields senderId, jobName, isScheduled, scheduledTime, and phoneNumbers are always filled in as they are marked with asterisks, indicating that they are mandatory.
  3. PhoneNumbers must be in this format "966558883879".
  4. Date and time is separated with a capital T.
  5. UTC time is defined with a capital letter Z.

Body

  1. {
  2. "senderId": "UUID of the sender",
  3. "jobName": "Job name or description",
  4. "isScheduled": false,
  5. "scheduledTime": "",
  6. "content": ["Message content"],
  7. "phoneNumbers": ["RecipientPhoneNumber"],
  8. "templateMessageId": "UUID of the template message"
  9. }
Response

SUCCESS

  1. {
  2. "success": true,
  3. "message": "Success",
  4. "data": {
  5. "message": "Message sent to queue, the status will be provided after a while"
  6. }
  7. }
Error Handling

If there is an error, such as Missing Key
FAILURE
  1. {
  2. "statusCode": 400,
  3. "message": {
  4. "message": [
  5. "each value in phoneNumbers must match /^9665[0-9]{8}$/ regular
  6. expression",
  7. "senderId must be a UUID",
  8. "senderId should not be empty",
  9. "jobName must be a string"
  10. ],
  11. "error": "Bad Request",
  12. "statusCode": 400
  13. },
  14. "success": false
  15. }
If there is an error, such as Has Not Subscribed

FAILURE
  1. {
  2. "statusCode": 404,
  3. "message": {
  4. "message": "Not Subscribed",
  5. "error": "Not Found",
  6. "statusCode": 404
  7. },
  8. "success": false
  9. }

Create OTP
Create and send an OTP message to a phone number. 


Parameters 




Notes:
  1. If the user provides a templateMessageId, they should leave the content field empty. Conversely, if the user fills in the content, they can leave the templateMessageId empty.
  2. Ensure that the fields senderId, jobName, isScheduled, scheduledTime, and phoneNumbers are always filled in as they are marked with asterisks, indicating that they are mandatory.
  3. PhoneNumbers must be in this format "966558883879".
  4. Date and time is separated with a capital T.
  5. UTC time is defined with a capital letter Z.
Body

  1. {
  2. "senderId": "UUID of the sender",
  3. "jobName": "Job name or description",
  4. "isScheduled": false,
  5. "scheduledTime": "",
  6. "content": ["OTP message content"],
  7. "phoneNumbers": ["RecipientPhoneNumber"],
  8. "templateMessageId": "UUID of the template message"
  9. }
Response

SUCCESS 
  1. {
  2. "success": true,
  3. "message": "Success",
  4. "data": {
  5.               "message": "Message sent to queue, the status will be provided after a while"
                }
  6. }
Error Handling

If there is an error, such as Missing Key 

FAILURE

  1. {
  2. "statusCode": 400,
    "message":
  3.                    { "message": [
  4.                                       "each value in phoneNumbers must match /^9665[0-9]{8}$/ regular expression",
  5.                                       "senderId must be a UUID",
  6.                                       "senderId should not be empty",
  7.                                       "jobName must be a string"
  8.                                        ],
  9.                                        "error": "Bad Request",
  10.                                        "statusCode": 400
  11.                         },
  12.                             "success": false 
  13. }
If there is an error, such as Has Not Subscribed

FAILURE

  1. {
  2. "statusCode": 404,
  3. "message": {
  4.                      "message": "Not Subscribed",
  5.                      "error": "Not Found",
  6.                      "statusCode": 404
  7.                     },
  8.                     "success": false
  9. }
Resend OTP
Resend an OTP message to a phone number. 


Parameters 



Notes:
  1. If the user provides a templateMessageId, they should leave the content field empty. Conversely, if the user fills in the content, they can leave the templateMessageId empty.
  2. Ensure that the fields senderId, jobName, isScheduled, scheduledTime, and phoneNumbers are always filled in as they are marked with asterisks, indicating that they are mandatory.
  3. PhoneNumbers must be in this format "966558883879".
  4. Date and time is separated with a capital T.
  5. UTC time is defined with a capital letter Z.
Body
  1. {
  2. "senderId": "UUID of the sender", 
  3. "jobName": "Job name or description",
  4. "isScheduled": false,
  5. "scheduledTime": "", "content": ["OTP message content"],
  6. "phoneNumbers": ["RecipientPhoneNumber"],
  7. "templateMessageId":"UUID of the template message"
  8. }
Response

SUCCESS 

  1. { "success": true,
  2. "message": "Success",
  3. "data": {
  4.           "message": "OTP ReSent successfully"
  5.        }
  6. }
Error Handling

If there is an error, such as Resend OTP

FAILURE

  1. {
  2. "statusCode": 400,
  3. "message": {
  4.                      "message": [
  5.                                          "each value in phoneNumbers must match /^9665[0-9]{8}$/ regular expression",
  6.                                          "senderId must be a UUID",
  7.                                          "senderId should not be empty",
  8.                                          "jobName must be a string"
  9.                     ],
  10.                       "error": "Bad Request",
  11.                       "statusCode": 400
  12.               },
  13.            "success": false
  14. }
If there is an error, such as Invalid Sender ID

FAILURE

  1. {
  2. "statusCode": 422,
  3. "message": {
  4.                      "message": "Client with the given ID does not exist",
  5.                      "error": "Unprocessable Entity",
  6.                      "statusCode": 422
  7.   },
  8.    "success": false
  9. }
Verify OTP

Verify an OTP sent to a phone number. 


Parameters
PhoneNumbers*
 number
 Recipient Phone Number

Body

  1. {
  2. "phoneNumber": "RecipientPhoneNumber",
  3. "otp": "123456"
  4. }
Response

SUCCESS 

  1. {
  2. "success": true,
  3. "message": "OTP verified successfull
  4. } 
Error Handling

If there is an error, such as PhoneNumber Problem

FAILURE

  1. {
  2. "statusCode": 400,
  3. "message": {
  4.             "message": [
  5.                           "phoneNumber must match /^9665[0-9]{8}$/ regular expression"
  6.                                     ],
  7.                            "error": "Bad Request",
  8.                            "statusCode": 400
  9.           },
  10.           "success": false
  11. } 
If there is an error, such as Not Found 

FAILURE

  1. {
  2.  "statusCode": 404,
  3. "message": {
  4.             "message": "Message not found",
  5.             "error": "Not Found",
  6.             "statusCode": 404 }, "success": false }


Create Bulk SMS

Send bulk SMS to multiple phone numbers.



Parameters


senderId *

string

The ID of the sender that you got from the Pervious step

jobName *

number

The name of the campaign.

isScheduled*

string

Indicates whether the message is

scheduled (yes/no). This field can contain values like 'true' or 'false'.

scheduledTime *

string

The time when the message should be sent if it's scheduled. Format it as a"2015- 03-25T12:00:00Z"

content

string

The body of the message to be sent. This field is optional if templateMessageId is provided.

Attachment*

File

CSV File with the Contact

templateMessageId

string

The ID of the template message if using predefined templates. If

provided, content can be left empty.


Notes:


  1. If the user provides a templateMessageId, they should leave the content field empty. Conversely, if the user fills in the content, they can leave the templateMessageId empty.
  2. Ensure that the fields senderId, jobName, isScheduled, scheduledTime, and phoneNumbers are always filled in as they are marked with asterisks, indicating that they are mandatory.
  3. Date and time is separated with a capital T.
  4. UTC time is defined with a capital letter Z.
Body 

  1. {
  2. "senderId": "UUID of the sender",
  3. "jobName": "Job name or description",
  4. "isScheduled": false,
  5. "scheduledTime": "",
  6. "content": [""],
  7. "attachment": "Sample File.csv"
  8. } 
Response

SUCCESS

  1. {
  2. "success": true,
  3. "message": "Success"
  4. }

Error Handling

If there is an error, such as No File

FAILURE

  1. {
  2. "statusCode": 422,
  3. "message": {
  4.                "message": "You must upload one file
  5.                "error": "Unprocessable Entity",
  6.                "statusCode": 422
  7.                   },
  8.                "success": false
  9. }
If there is an error, such as Invalid Sender 

FAILURE

  1. {
  2. "statusCode": 422,
  3. "message": {
  4.                      "message": "Client with the given ID does not exist",
  5.                      "error": "Unprocessable Entity",
  6.                      "statusCode": 422
  7.                },
  8.                 "success": false
  9. }


Get All Messages

Send bulk SMS to multiple phone numbers



Parameters


page *

Integer

The page number of the results to retrieve. Used for pagination.

limit *

Integer

The number of results per page. Controls the size of each paginated result set.



Response
Get All

SUCCESS

  1. {
  2. "success": true,
  3. "message": "Success",
  4. "data": [
  5.               {
  6.                 "id": "89c4b2f8-b503-4592-8213-00127552b501",
  7.                 "jobId": "66814898-1036-4710-8e74-19515fc0a037",
  8.                 "workspaceId": "d51fd261-9c0a-4406-a408-41ec053af797",
  9.                 "senderId": "e5e5d04d-01f2-4cf0-9250-ab272693ab7b",
  10.                "senderIdName": "Bevatel5",
  11.                "otp": null,
  12.                "phoneNumber": "966558883879",
  13.                "content": "TEST",
  14.                "status": 0,
  15.                "sentAt": null,
  16.               "createdAt": "2024-09-25T11:20:42.822Z",
  17.               "updatedAt": "2024-09-25T11:20:42.822Z",
  18.               "deletedAt": null,
  19.               "batchId": null,
  20.               "otpSendingDate": "2024-09-25T11:12:53.740Z",
  21.               "otpStatus": 0
  22.             },
  23.              {
  24.             "id": "ca23eb8b-51cd-4943-8855-f613f52e3d30",
  25.             "jobId": "f0a38285-ff66-440b-a181-c02f981c51d8",
  26.             "workspaceId": "d51fd261-9c0a-4406-a408-41ec053af797",
  27.             "senderId": "e5e5d04d-01f2-4cf0-9250-ab272693ab7b",
  28.             "senderIdName": "Bevatel5",
  29.             "otp": null,
  30.            "phoneNumber": "966558883879",
  31.            "content": "TEST",
  32.            "status": 0,
  33.            "sentAt": null,
  34.            "createdAt": "2024-09-25T11:24:05.237Z",
  35.            "updatedAt": "2024-09-25T11:24:05.237Z",
  36.            "deletedAt": null,
  37.            "batchId": null,
  38.            "otpSendingDate": "2024-09-25T11:12:53.740Z",
  39.            "otpStatus": 0
  40.                }
  41.             ],
  42.            "meta": {
  43.                       "current_page": 1,
  44.                       "from": 1,
  45.                       "last_page": 1,
  46.                       "per_page": 10,
  47.                       "to": 2,
  48.                       "total": 2
  49.            }
  50. }
   
Response

PAGE AND LIMIT

SUCCESS

  1. {
  2.     "success": true, 
  3.     "message": "Success", 
  4.      "data": [
  5.           {
  6.                     "id": "89c4b2f8-b503-4592-8213-00127552b501",
  7.                     "jobId": "66814898-1036-4710-8e74-19515fc0a037",
  8.                     "workspaceId": "d51fd261-9c0a-4406-a408-41ec053af797",
  9.                     "senderId": "e5e5d04d-01f2-4cf0-9250-ab272693ab7b",
  10.                     "senderIdName": "Bevatel5",
  11.                     "otp": null,
  12.                    "status": 0,
  13.                    "phoneNumber": "966558883879", 
  14.                     "content": "TEST", 
  15.                    "status": 0, 
  16.                    "sentAt": null,
  17.                    "createdAt": "2024-09-25T11:20:42.822Z",
  18.                    "updatedAt": "2024-09-25T11:20:42.822Z",
  19.                    "deletedAt": null,
  20.                    "batchId": null,
  21.                    "otpSendingDate": "2024-09-25T11:12:53.740Z",
  22.                   "otpStatus": 0
  23.       },
  24.   {
  25.               "id": "a989d19e-2507-442a-848b-51debb4f1fef",
  26.               "jobId": "92b0a1fa-16c5-46c8-95f8-20d8cc2a55c2",
  27.               "workspaceId": "d51fd261-9c0a-4406-a408-41ec053af797",
  28.               "senderId": "e5e5d04d-01f2-4cf0-9250-ab272693ab7b",
  29.               "senderIdName": "Bevatel5",
  30.               "otp": null,
  31.              "phoneNumber": "+966 12 398 7654",
  32.              "content": "TEST",
  33.              "status": 0,
  34.              "sentAt": null,
  35.              "createdAt": "2024-09-25T11:28:06.488Z",
  36.              "updatedAt": "2024-09-25T11:28:06.488Z",
  37.              "deletedAt": null,
  38.              "batchId": null,
  39.              "otpSendingDate": "2024-09-25T11:12:53.740Z",
  40.              "otpStatus": 0
  41.       }
  42.  ],
  43.           "meta": {
  44.                     "current_page": 1,
  45.                     "from": 1,
  46.                     "last_page": 1, 
  47.                     "per_page": 25,
  48.                     "to": 2,
  49.                     "total": 2
  50.        }
  51.  } 


Get Message by ID

Send bulk SMS to multiple phone numbers


Idea
GET https://bevatel-system-api.bevatel.com/sms/developer/v1/{{message-ID}}

Parameters



message-ID *

string

The ID of the message that you got from the Pervious step


Response

Get One Message

SUCCESS


  1. {
  2.     "success": true,
  3.      "message": "Success",
  4.      "data": { "id": "89c4b2f8-b503-4592-8213-00127552b501",
  5.      "jobId": "66814898-1036-4710-8e74-19515fc0a037",
  6.      "workspaceId": "d51fd261-9c0a-4406-a408-41ec053af797",
  7.      "senderId": "e5e5d04d-01f2-4cf0-9250-ab272693ab7b",
  8.      "senderIdName": "Bevatel5",
  9.      "otp": null,
  10.      "phoneNumber": "966558883879",
  11.      "content": "TEST",
  12.      "status": 0,
  13.      "sentAt": null,
  14.      "createdAt": "2024-09-25T11:20:42.822Z",
  15.      "updatedAt": "2024-09-25T11:20:42.822Z",
  16.      "deletedAt": null,
  17.      "batchId": null,
  18.      "otpSendingDate": "2024-09-25T11:12:53.740Z",
  19.      "otpStatus": 0,
  20.      "client": null,
  21.      "template": null
  22.     } 
  23. } 
Error Handling

Response

Not Found Message

FAILURE
  1. {
  2. "statusCode": 404,
  3. "message": {
  4. "message": "Message not found",
  5. "error": "Not Found",
  6. "statusCode": 404
  7. },
  8. "success": false
  9. }

Reports

This endpoint retrieves job messages based on the specified filters and pagination settings.



Parameters



type *

string

Based on the type of job (Quick or Bulk).

page *

integer

The page number to retrieve for pagination. Default is 1.

limit *

integer

The number of items per page. Example: 3 to retrieve three items per page.

Authorization *

String

Bearer token obtained from the

authentication step. Must be formatted as Bearer {token}.


Note: The Bearer token is the API token you receive in the first step of the authentication process. Ensure you include this token in the Authorization header for all subsequent requests.

Response

Fetch All Jobs

SUCCESS

  1. { 
  2. "success": true,
  3.             "message": "Success",
  4.             "data": [
  5.                   {
  6.                            "name": "sadsadsadsad",
  7.                            "senderName": "Bevatel5",
  8.                            "id": "66814898-1036-4710-8e74-19515fc0a037",
  9.                            "type": "quick",
  10.                            "failedCount": 0,
  11.                            "pendingCount": 1,
  12.                            "sentCount": 0,
  13.                            "total": 1,
  14.                            "status": "finished",
  15.                            "startedAt": "2024-09-25T11:20:42.799Z"
  16.        },
  17.       {
  19.                "name": "sadsadsadsad",
  20.                 "senderName": "Bevatel5",
  21.                "id": "f0a38285-ff66-440b-a181-c02f981c51d8
  22.                "type": "quick",
  23.                "failedCount": 0,
  24.                "pendingCount": 1,
  25.                "sentCount": 0,
  26.                "total": 1,
  27.                "status": "finished
  28.                "startedAt": "2024-09-25T11:24:05.218Z"
  29.         },
  30.         {
  31.                "name": "sadsadsadsad",
  32.                "senderName": "Bevatel5",
  33.                "id": "92b0a1fa-16c5-46c8-95f8-20d8cc2a55c2",
  34.                "type": "quick",
  35.                "failedCount": 0,
  36.                "pendingCount": 2,
  37.                "sentCount": 0,
  38.                "total": 2,
  39.                "status": "finished
  40.                "startedAt": "2024-09-25T11:28:06.461Z"
  41.       }
  42.       ],
  43.                "meta": {
  44.                "current_page": 1,
  45.                "from": 1,
  46.                "last_page": 1,
  47.                "per_page": 10,
  48.                "to": 3,
  49.                "total": 3
  50. }
  51. }


Delete Job



Parameters



job-ID *

string

The ID of the job that you got from the Pervious step


Response

Fetch All Jobs

SUCCESS

  1. {
  2. "success": true,
  3. "message": "Success"
  4. }
Error Handling

Response

Not Found Job

FAILURE

  1. {
  2. "statusCode": 404,
  3. "message": {
  4. "message": "MessageJob not found",
  5. "error": "Not Found",
  6. "statusCode": 404
  7. },
  8. "success": false
  9. }
Cannot Delete A started job

FAILURE

  1. {
  2. "statusCode": 400,
  3. "message": {
  4. "message": "Cannot delete a job that has already started",
  5. "error": "Bad Request",
  6. "statusCode": 400
  7. },
  8. "success": false
  9. }