Route Mobile Bulk Campaigns API

openapi: 3.2.0
info:
  version: 1.8.0
  title: Route Mobile WhatsApp Business Bulk Campaigns API
  description: The Route Mobile WhatsApp Business API enables enterprises to programmatically send and receive WhatsApp messages at scale.
  contact:
    name: Route Mobile Developer Support
    url: https://developers.routemobile.com/
    email: product-desk@routemobile.com
  termsOfService: https://www.routemobile.com/terms-of-service/
  license:
    name: Proprietary
    url: https://www.routemobile.com/terms-of-service/
  x-logo:
    url: https://www.routemobile.com/wp-content/uploads/2023/04/route-mobile-logo.svg
    altText: Route Mobile
servers:
- url: https://apis.rmlconnect.net
security:
- BearerAuth: []
tags:
- name: Bulk Campaigns
  description: Upload files, create, start, pause, and resume bulk messaging campaigns to reach large audiences.
paths:
  /wba/v2/upload:
    post:
      tags:
      - Bulk Campaigns
      summary: File Upload
      description: The File Upload API sends multiple messages to users in a single upload.
      operationId: fileUpload
      parameters:
      - name: source
        in: query
        description: The details of the source for uploading the file for a bulk campaign.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: UI
      - name: debug
        in: query
        description: The parameter that enables or disables the debug mode.   Set the default value of "debug=True" to enable the debug mode. The system generates additional information and logs to help resolving troubleshoot and debug issues with the bulk campaigns.
        style: form
        explode: true
        schema:
          enum:
          - 'True'
          - 'False'
          example: 'True'
      requestBody:
        description: Upload a CSV or text file containing recipient phone numbers and message content for a bulk campaign.
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BulkUploadRequest'
            examples:
              Example:
                value:
                  campaign_type: string
                  file: string
                  file_mimetype: string
                  filename: string
                  message: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUploadResponse'
              examples:
                Example 1:
                  value:
                    message: File uploaded successfully
                    campaign_id: 670b3fd4-d442-11ed-a821-xxxxxxxxxxxx
                    file_type: text/csv
                    file_size: 19.0B
                    total_records: 1
                    valid_records: 1
                    duplicate records: 0
                    campaign_type: generalized
                    message_preview:
                      phone: '{phone}'
                      enable_acculync: true
                      extra: '{''asd'':''asd''}'
                      media:
                        type: media_template
                        template_name: boarding_pass_update
                        lang_code: en
                        header:
                        - image:
                            link: https://media.istockphoto.com/vectors/airplane-ticket-boarding-pass-ticket-template-vector-id878xxxxxx
                        body:
                        - text: Here is your boarding pass
                    asynchronous: false
                    country_code: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwtExpiredError'
              examples:
                JWT Token Expired:
                  value:
                    message: unable to process campaign request
                    reason: jwt token expired
                    status: failure
        '404':
          description: Page Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
              examples:
                Incorrect API URL:
                  value:
                    message: The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/UnknownCampaignTypeError'
                - $ref: '#/components/schemas/FileMimetypeError'
              examples:
                Unknown campaign type:
                  value:
                    message: please check API docs for more info
                    status: failed
                    reason:
                      campaign_type:
                      - 'Must be one of: generalized, personalized.'
                File Mimetype error:
                  value:
                    message: please check API docs for more info
                    status: failed
                    reason:
                      file_mimetype:
                      - 'Must be one of: text/csv, text/plain, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.spreadsheetml.template, application/vnd.ms-excel.sheet.macroEnabled.12, application/vnd.ms-excel.template.macroEnabled.12, application/vnd.ms-excel.addin.macroEnabled.12, application/vnd.ms-excel.sheet.binary.macroEnabled.12.'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The status of the message delivery.
                  message:
                    type: string
                    description: The message response.
              examples:
                Internal server error:
                  value:
                    status: failure
                    message: unable to process request
      security:
      - BearerAuth: []
  /wba/v2/manage_campaign:
    post:
      tags:
      - Bulk Campaigns
      summary: Send Bulk Campaign
      description: The Send Bulk Campaign API sends messages in bulk to multiple users, manages large-scale campaigns, and reduces the workload for marketers or business owners.
      operationId: sendBulkCampaign
      parameters:
      - name: debug
        in: query
        description: The parameter that enables or disables the debug mode.   Set the default value of "debug=True" to enable the debug mode. The system generates additional information and logs to help resolving troubleshoot and debug issues with the bulk campaigns.
        style: form
        explode: true
        schema:
          enum:
          - 'True'
          - 'False'
          example: 'True'
      - name: source
        in: query
        description: The details of the source for uploading the file for a bulk campaign.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: UI
      requestBody:
        description: Start, pause, or resume a bulk messaging campaign.
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/StartCampaignRequest'
              - $ref: '#/components/schemas/ResumeCampaignRequest'
              - $ref: '#/components/schemas/PauseCampaignRequest'
            examples:
              Start Campaign:
                value:
                  campaign_action: start
                  campaign_id: '{campaign id}'
                  campaign_name: '{campaign name}'
                  file_mimetype: text/plain or text/csv
                  filename: '{filename with extension}'
                  payload:
                    type: '{payload type}'
                  scheduled_time: '{date and time in UTC e.g.2021-12-08 13:36:00}'
              Pause Campaign:
                value:
                  campaign_action: pause
                  campaign_id: '{campaign id}'
              Resume Campaign:
                value:
                  campaign_action: resume
                  campaign_id: '{campaign id}'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignAcceptedResponse'
              examples:
                Example:
                  value:
                    status: success
                    message: campaign with id 670b3fd4-d442-11ed-a821-xxxxxxxxxxxx is now processing
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignBadRequestError'
              examples:
                Filename Mismatch:
                  value:
                    status: failed
                    message: unable to process request
                    reason: file name mismatch between /upload and /campaign endpoints for 670b3fd4-d442-11ed-a821-xxxxxxxxxxxx
        '401':
          description: Authentication Failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignAuthError'
              examples:
                JWT Token Expired:
                  value:
                    status: failed
                    message: unable to process request
                    reason: jwt token expired
        '404':
          description: Page Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
              examples:
                Incorrect API URL:
                  value:
                    message: The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/IncorrectPayloadTypeError'
                - $ref: '#/components/schemas/IncorrectCampaignIdError'
              examples:
                Incorrect Payload Type:
                  value:
                    message: please check API docs for more info
                    status: failed
                    reason:
                      payload:
                      - Unable to check payload type
                Incorrect Campaign ID:
                  value:
                    message: please check API docs for more info
                    status: failed
                    reason:
                      campaign_id:
                      - Not a Valid Campaign Id
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The status of the bulk campaign.
                  message:
                    type: string
                    description: The response message.
                  reason:
                    type: string
                    description: The reason for not processing the request.
              examples:
                Example:
                  value:
                    status: failed
                    message: unable to process request
                    reason: <internal server error reason>
      security:
      - BearerAuth: []
components:
  schemas:
    MessagePreviewMediaHeader:
      type: object
      properties:
        image:
          $ref: '#/components/schemas/MessagePreviewMediaImage'
    BulkUploadResponse:
      type: object
      properties:
        message:
          type: string
          description: The outcome of the file upload process.
        campaign_id:
          type: string
          description: The unique identifier for the campaign associated with the uploaded file.
        file_type:
          type: string
          description: The type of the uploaded file.
        file_size:
          type: string
          description: The size of the uploaded file.
        total_records:
          type: integer
          description: The total number of records present in the uploaded file.
        valid_records:
          type: integer
          description: The count of valid records within the uploaded file.
        duplicate records:
          type: integer
          description: The count of duplicate records found in the uploaded file.
        campaign_type:
          type: string
          description: The type of campaign being sent, which can be either generalized or personalized.
        message_preview:
          $ref: '#/components/schemas/MessagePreview'
        asynchronous:
          type: boolean
          description: The parameter indicates whether the file upload process is synchronous or asynchronous.
        country_code:
          type: string
          description: The country code.
    FileMimetypeError:
      type: object
      title: File Mimetype Error
      properties:
        message:
          type: string
          description: The response message.
        status:
          type: string
          description: The status of the file upload.
        reason:
          type: object
          description: The reason for not processing the file upload request.
          properties:
            file_mimetype:
              type: array
              description: The MIME type of the file containing the phone numbers of the recipients.
              items:
                type: string
    PauseCampaignRequest:
      type: object
      properties:
        campaign_action:
          type: string
          description: The action to be taken for the campaign. For sending a bulk campaign, the value should be set to "pause".
          example: '"pause"'
        campaign_id:
          type: string
          description: The unique identifier for the campaign. This ID is generated by WhatsApp when you execute the File Upload API.
          example: 670b3fd4-xxxx-11ed-a821-xxxxxxxxxxxx
      required:
      - campaign_action
      - campaign_id
    ResumeCampaignRequest:
      type: object
      properties:
        campaign_action:
          type: string
          description: The action to be taken for the campaign. For sending a bulk campaign, the value should be set to "resume".
          example: '"resum"'
        campaign_id:
          type: string
          description: The unique identifier for the campaign. This ID is generated by WhatsApp when you execute the File Upload API.
          example: 670b3fd4-xxxx-11ed-a821-xxxxxxxxxxxx
      required:
      - campaign_action
      - campaign_id
    NotFoundError:
      type: object
      properties:
        message:
          type: string
          description: The message response.
    UnknownCampaignTypeError:
      type: object
      title: Unknown Campaign Type Error
      properties:
        message:
          type: string
          description: The response message.
        status:
          type: string
          description: The status of the file upload.
        reason:
          type: object
          description: The reason for not processing the file upload request.
          properties:
            campaign_type:
              type: array
              description: The type of the campaign.
              items:
                type: string
    MessagePreview:
      type: object
      description: A preview of the message or content associated with the campaign.
      properties:
        phone:
          type: string
          description: The mobile number of the recipient in full international format.
        enable_acculync:
          type: boolean
          description: A boolean indicating whether or not to enable Acculync.
        extra:
          type: string
          description: Additional information to include in the message.
        media:
          $ref: '#/components/schemas/MessagePreviewMedia'
    BulkUploadRequest:
      type: object
      properties:
        campaign_type:
          type: string
          description: The type of campaign being sent, which can be either generalized or personalized.
          example: Generalized
        file:
          type: string
          description: "The CSV or plain text file path on your local system or network that you want to upload as part of a bulk campaign. The file contains the list of phone numbers and messages. \n\nSee the sample files for more information on bulk upload files and their details:\n- [Bulk Upload File](https://github.com/routemobile/WhatsApp-Business-API/blob/master/Sample%20Bulk%20Upload%20File.txt)\n- [Bulk Upload Campaign File](https://github.com/routemobile/WhatsApp-Business-API/blob/master/Sample%20Bulk%20Upload%20Campaign%20File.xlsx)\n- [Campaign File](https://github.com/routemobile/WhatsApp-Business-API/blob/master/Sample%20Campaign%20File%20.csv)"
          example: ABC.xlsx, ABC.csv, ABC.txt
        file_mimetype:
          type: string
          description: The MIME type of the file containing the phone numbers of the recipients. The type of the file can be either "text/plain" or "text/csv".
          example: '"text/plain or text/csv"'
        filename:
          type: string
          description: The name of the file containing the phone numbers of the recipients, including the file extension.
        message:
          type: string
          description: The message that you want to send to the users along with the file.
      required:
      - campaign_type
      - file
      - file_mimetype
      - filename
      - message
    IncorrectPayloadTypeError:
      type: object
      title: Incorrect Payload Type Error
      properties:
        message:
          type: string
          description: The response message.
        status:
          type: string
          description: The status of the bulk send campaign.
        reason:
          type: object
          description: The reason for not processing the bulk send campaign request.
          properties:
            payload:
              type: array
              description: An object representing the message to be sent.
              items:
                type: string
    CampaignPayload:
      type: object
      description: An object representing the template type, such as media template.
      properties:
        type:
          type: string
          description: The type of the payload depends on the type of message being sent as part of a bulk campaign.
          example: '"Text"'
      required:
      - type
    CampaignAuthError:
      type: object
      properties:
        status:
          type: string
          description: The status of the message.
        message:
          type: string
          description: The response message.
        reason:
          type: string
          description: The reason for not processing the message.
    MessagePreviewMediaImage:
      type: object
      properties:
        link:
          type: string
          description: The URL of the image file.
    IncorrectCampaignIdError:
      type: object
      title: Incorrect Campaign ID Error
      properties:
        message:
          type: string
          description: The response message.
        status:
          type: string
          description: The status of the bulk send campaign.
        reason:
          type: object
          description: The reason for not processing the bulk send campaign request.
          properties:
            campaign_id:
              type: array
              description: The unique ID of the campaign.
              items:
                type: string
    CampaignBadRequestError:
      type: object
      properties:
        status:
          type: string
          description: The status of the message.
        message:
          type: string
          description: The response message.
        reason:
          type: string
          description: The reason for not processing the message.
    StartCampaignRequest:
      type: object
      properties:
        campaign_action:
          type: string
          description: The action to be taken for the campaign. For sending a bulk campaign, the value should be set to "start".
          example: '"start"'
        campaign_id:
          type: string
          description: The unique identifier for the campaign. This ID is generated by WhatsApp when you execute the File Upload API.
          example: 670b3fd4-xxxx-11ed-a821-xxxxxxxxxxxx
        campaign_name:
          type: string
          description: The name of the campaign.
          example: '{campaign name}'
        file_mimetype:
          type: string
          description: The MIME type of the file containing the phone numbers of the recipients. The type of the file can be in different formats, such as "text/plain" or "text/csv".
          example: '"text/plain or text/csv"'
        filename:
          type: string
          description: The name of the file containing the phone numbers of the recipients, including the file extension.
          example: '{filename with extension}'
        payload:
          $ref: '#/components/schemas/CampaignPayload'
        scheduled_time:
          type: string
          description: The date and time at which the campaign should be scheduled to start, in UTC format. The format of the string should be "YYYY-MM-DD HH:mm:ss".
          example: '"2021-12-08 13:36:00"'
      required:
      - campaign_action
      - campaign_id
      - campaign_name
      - file_mimetype
      - filename
      - payload
      - scheduled_time
    CampaignAcceptedResponse:
      type: object
      properties:
        status:
          type: string
          description: The status of the message.
        message:
          type: string
          description: The response message.
    MessagePreviewMediaBody:
      type: object
      properties:
        text:
          type: string
          description: The text to include in the message.
    JwtExpiredError:
      type: object
      properties:
        message:
          type: string
          description: The response message.
        reason:
          type: string
          description: The reason for not processing the product feed update request.
        status:
          type: string
          description: The status of the product feed update.
    MessagePreviewMedia:
      type: object
      properties:
        type:
          type: string
          description: The type of message template.
        template_name:
          type: string
          description: The name of the template to use.
        lang_code:
          type: string
          description: Language code of language in which message text is written, such as "en" for English.
        header:
          type: array
          items:
            $ref: '#/components/schemas/MessagePreviewMediaHeader'
        body:
          type: array
          items:
            $ref: '#/components/schemas/MessagePreviewMediaBody'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JSON Web Token obtained from the Login API. Include the token in the `Authorization` header as `Bearer <token>`. Tokens expire after one hour by default.
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true