CALLBACK RESPONSE

We strongly recommend including a callbackUrl to receive updates on sent messages. The callback response provides an accurate representation of the message and includes the following fields:

Message Status Enum

The MESSAGE_STATUS enum represents the different states a message can be in:

• pending The message is being processed.
• sent The message has been successfully sent.
• failed The message could not be delivered.
• cancel The message was canceled before sending.
• spam The message was flagged as spam.
• queue The message is waiting in the queue to be sent.

EXAMPLE OF CALLBACK RESPONSE

      
      {
        messageId: 'Gy2tr24Ti3UgRTiXOZq3',
        message: 'Hello',
        status: 'sent',
        countryCode: 'np',
        report: [
            {
            number: '98XXXXXXXX',
            status: 'success',
            creditCount: 1
            },
            {
            number: '98YYYYYYYY',
            status: 'failed',
            message: 'number not available',
            creditCount: 1
            }
        ],
        failed: 1,
        senderId: 'bit_alert',
        deliveredDate: '2024-12-16T08:01:01.762Z',
        refunded: 1
      }
      
    

SEND DYNAMIC MESSAGES IN BULK

This endpoint allows users to send dynamic message. A dynamic message allows users to send personalized content to multiple recipients in a single request. Unlike static messages, where the same content is sent to all recipients, dynamic messages are customized for each recipient using placeholders or variables.

Additionally, it allows users to include a callback URL to receive a detailed report after the SMS is sent.

ROUTE: https://api.bitmoro.com/message/api/dynamic

REQUEST-METHOD: POST

REQUEST-HEADERS :

To successfully send a request to this endpoint, the following headers must be included in the request:

• Authorization: This header must contain a valid bearer token in the format Bearer <token>, where <token> is your authentication token.
• Content-Type: This should be set to application/json to indicate that the request body contains JSON data.
• Content-Length: This should reflect the length of the request body in bytes.

"headers": {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json",
    "Content-Length": "<length_of_your_data>"
}

Request Body

Note: ensure that no extra fields are present in the request body.

Example Request Body

{
  contacts: [
    {number: "98XXXXXXXX", name: "joe"},
    {number: "98YYYYYYYY"},
    {number: "98ZZZZZZZZ", city: "kathmandu"}
  ],
  message: "Hello ${name}. I am from ${city}",
  countryCode:"np",
  callbackUrl: "http://192.168.1.10:4000/test",
  scheduledDate: Date.now() + 1000 * 60,
  defaultValues: {name: "ramu", city: "Biratnagar"}
}

SUCCESS RESPONSE

Example Success Response

    {
      status: 'QUEUED',
      report: [
        {
          to: '98XXXXXXXX',
          messageId: 'PjTii5xfoL1nKRFveMTt',
          from: 'BIT_MORE',
          text: 'Hello Joe. I am from Biratnagar.',
          type: 1,
          credit: 1
        },
        {
          to: '98YYYYYYYY',
          messageId: 'PjTii5xfoL1nKRFveMTt',
          from: 'BIT_MORE',
          text: 'Hello Ramu. I am from Biratnagar.',
          type: 1,
          credit: 1
        },
        {
          to: '98ZZZZZZZZ',
          messageId: 'PjTii5xfoL1nKRFveMTt',
          from: 'BIT_MORE',
          text: 'Hello Ramu. I am from Kathmandu.',
          type: 1,
          credit: 1
        }
      ],
      creditSpent: 3,
      messageId: 'PjTii5xfoL1nKRFveMTt',
      senderId: 'BIT_MORE',
      countryCode: 'np'
    }
  

• SEND MESSAGES IN BATCH

  This endpoint allows the user to send messages in batch to the specified phone numbers. The request body must include a list of phone numbers, the message content, and an optional sender ID.

  This endpoint is given high priority in the queue.

  ROUTE: https://api.bitmoro.com/message/api

  REQUEST-METHOD: POST

  REQUEST-HEADERS:

  To successfully send a request to this endpoint, the following headers must be included in the request:

  • Authorization: This header must contain a valid bearer token in the format Bearer <token>, where <token> is your authentication token.
  • Content-Type: This should be set to application/json to indicate that the request body contains JSON data.
  • Content-Length: This should reflect the length of the request body in bytes.

  {
    "headers": {
      "Authorization": "Bearer <your_token>",
      "Content-Type": "application/json",
      "Content-Length": "<length_of_your_data>"
    }
  }
        

  Request Body

  The request body should be a JSON object with the following fields:

  Field	Type	Description	Required
  number	array	An array of valid phone numbers to send the message to.	Yes
  message	string	The message content that will be sent.	Yes
  senderId	string	An optional field to specify the sender ID.	No
  countryCode	string	The code of the country (e.g. np, in,us).	Yes

  Note: ensure that no extra fields are present in the request body.

  Example Request Body:

  {
    "number": ["98XXXXXXXX", "98XXXXXXXXX"],
    "message": "Hello, this is a test message!",
    "senderId": "bit_alert",
    "countryCode":"np",
    "countryCode":"np"
  }
        

  SUCCESS RESPONSE

  Field	Type	Description
  messageId	string	A unique identifier for the message.
  status	QUEUED	QUEUED indicates it's in the queue to be sent.
  statusUrl	string	The API endpoint to fetch message delivery status using your API token.

  Example Of Success Response:

  {
    "messageId": "tqtkIYTQpSAneKYMLJEC",
    "status": "QUEUED",
    "statusUrl": "https://api.bitmoro.com/message/message-report/y9tjZBqBpQhzkArRSqdA"
  }
        

  ERROR RESPONSE

  Every required field must be provided in the request. If any required field is missing, the API will return a 400 error with a clear, descriptive message indicating which field(s) are absent.
  Note: Once a message is added to the dispatch queue, it is considered processed, and no further error responses will be returned. Errors are only returned for invalid requests or those that fail before reaching the queue. Messages in the queue are sent unless flagged as spam, in which case they are dropped.

  ErrorCode	ErrorMessage	StatusCode
  01	Must include auth header	400
  02	Invalid Authorization Format	400
  03	Permission not granted for ip ${ip}	403
  04	Number length cannot exceed 100 for instant use	400
  05	Cannot send message until the number is verified	403
  06	Insufficient credit for user with ID: ${userId}	400
  08	Invalid api token	403
  09	No senderId found	400
  10	Choosen senderId is not active contact admin	400
  11	Choosen senderId has crossed billing cycle contact admin for renewal	400
  12	Choosen senderId is not active, contact your organization	400
  14	Account deactivated due to spamming contact admin	403
  19	No numbers found	400
  18	Can't find any valid nepali numbers	400

  Example Of Error Response

  {
    "message": "Cannot send message until the number is verified",
    "errorCode": "05"
  }
        

  WARN: - You cannot send the same message to a number more than three times within a 5-minute window. Each message must differ by at least 5%. Otherwise, it will be flagged as spam and dropped. Repeated spamming may result in the deactivation of the user.
  - The maximum number of recipients for a single request is 100. If you need to send messages to more than 100 recipients, you can use the SEND MESSAGES IN BULK endpoint.