Route Mobile Viber Business Messaging API

openapi: 3.2.0
info:
  version: 1.5.0
  title: Route Mobile Viber OpenAPI Specification Viber Business Messaging API
  description: Welcome to the Route Mobile developer hub. You'll find comprehensive Viber API documentation to help you start working with Route Mobile as quickly as possible, as well as support if you get stuck. Let's jump right in!
  contact:
    url: https://developers.routemobile.com/
    name: Route Mobile Development
    email: support@routemobile.com
  license:
    name: Proprietary
    url: https://www.routemobile.com/terms-conditions/
  x-logo:
    url: https://routemobile.github.io/Viber-Business-Messages-API/Logo.png
    backgroundColor: '#FFFFFF'
    altText: RouteMobile logo
servers:
- url: https://apis.rmlconnect.net
- url: '{client callback}'
security:
- jwt: []
tags:
- name: Viber Business Messaging API
  description: Send single messages to individual Viber users including text, images, videos, files, OTP verification, and interactive buttons. Also manage campaign file uploads and legacy campaign send operations.
paths:
  /vbs/api/v2/send:
    post:
      tags:
      - Viber Business Messaging API
      summary: Viber Send Single Messages APIs
      description: 'Viber Business Send Messages APIs allow businesses to send a variety of message types to their users on the Viber platform. These APIs enable businesses to engage with their customers, deliver personalized content, and provide interactive experiences through Viber''s messaging platform.


        Here are the supported Viber Business Send Single Message types:


        - **Single Text:** Send a plain text message to a recipient.

        - **Single Text Button:** Send a text message with an action button.

        - **Single Text Button Image:** Send a message combining text, a button, and an image.

        - **Single Text Image:** Send a message combining text and an image.

        - **Single Image:** Send a standalone image message.

        - **Single File:** Send a file/document attachment.

        - **Single Video:** Send a video message.

        - **Single Video Text:** Send a video with accompanying text.

        - **Single Video Button Text:** Send a video with text and an action button.

        - **Single Video Text Action Button:** Send a video with text and a structured action button object.

        - **OTP / Verification Message:** Send a one-time password or verification code using a pre-approved template.

        - **Text Template:** Send a branded text message using an approved template ID.

        - **Text Message with Fallback:** Send a Viber message with an automatic fallback to WhatsApp or SMS if the recipient is unreachable on Viber.'
      operationId: singleVideoText
      x-readme:
        samples-languages:
        - curl
        - python
        - node
        - java
        - php
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/vbs_single_textbuttonimg_msg'
              - $ref: '#/components/schemas/vbs_single_textbutton_msg'
              - $ref: '#/components/schemas/vbs_single_text_msg'
              - $ref: '#/components/schemas/vbs_single_textimage_msg'
              - $ref: '#/components/schemas/vbs_single_image_msg'
              - $ref: '#/components/schemas/vbs_single_file_msg'
              - $ref: '#/components/schemas/vbs_single_video_msg'
              - $ref: '#/components/schemas/vbs_single_videotext_msg'
              - $ref: '#/components/schemas/vbs_single_video_button_text_msg'
              - $ref: '#/components/schemas/vbs_single_video_text_action_button_msg'
              - $ref: '#/components/schemas/vbs_single_otp_msg'
              - $ref: '#/components/schemas/vbs_single_text_template_msg'
              - $ref: '#/components/schemas/vbs_single_fallback_msg'
            examples:
              Single Text Button Image:
                value:
                  phone: '{mobile with country code}'
                  text: '{text}'
                  button_text: '{button text}'
                  button_link: '{button link with https://}'
                  img: '{image link with https:// with extension}'
                  ttl: '{time in seconds}'
                  message_type: template
                  method: one_way/two_way
              Single Text Button:
                value:
                  phone: '{mobile with country code}'
                  text: '{text}'
                  button_text: '{button text}'
                  button_link: '{button link with https://}'
                  message_type: media
                  method: one_way/two_way
              Single Text:
                value:
                  phone: '{mobile with country code}'
                  text: '{text}'
                  message_type: text
                  method: one_way/two_way/session
              Single Image:
                value:
                  phone: '{mobile with country code}'
                  img: '{image link with https:// with extension}'
                  ttl: '{time in seconds}'
                  message_type: image
                  method: two_way/session
              Single File:
                value:
                  phone: '{mobile with country code }'
                  message_type: file
                  method: two_way/session
                  ttl: '{time in seconds}'
                  file_url: '{file link with https:// with extension}'
                  file_name: test
              Single Video:
                value:
                  phone: '{mobile with country code}'
                  message_type: video
                  method: two_way
                  ttl: '{time in seconds}'
                  video: '{video link with https:// with extension'
                  thumbnail_url: '{image link with https:// with extension}'
              Single Video Text:
                value:
                  phone: '{mobile with country code}'
                  video: '{video link with https:// with extension}'
                  text: '{body text}'
                  ttl: '{time in seconds}'
                  message_type: text_video
                  method: two_way
              Single Text Image:
                value:
                  phone: '{mobile with country code}'
                  message_type: text_image
                  method: promotion
                  img: '{image link with https:// with extension}'
                  text: '{body text}'
                  tracking_data: '{tracking data}'
              Single Video Button Text:
                value:
                  phone: '{mobile with country code}'
                  message_type: video_action
                  method: promotion
                  video: '{video link with https:// with extension}'
                  text: '{body text}'
                  thumbnail_url: '{thumbnail image link with https:// with extension}'
                  button_text: '{button text}'
              Single Video Text Action Button:
                value:
                  phone: '{mobile with country code}'
                  message_type: video_text_action_button
                  method: promotion
                  video: '{video link with https:// with extension}'
                  text: '{body text}'
                  thumbnail_url: '{thumbnail image link with https:// with extension}'
                  button:
                    button_url: '{button url with https://}'
                    button_text: '{button text}'
              OTP Verification Message:
                value:
                  phone: '{mobile with country code}'
                  message_type: verify_otp
                  method: verify
                  template:
                    template_id: '{template UUID}'
                    template_params:
                      pin: '{otp code}'
                      business_platform_name: '{business name}'
                    template_lang: en
              Text Template:
                value:
                  phone: '{mobile with country code}'
                  message_type: text_template
                  method: transaction
                  text: '{message text}'
                  tracking_data: '{tracking data}'
              Text with Fallback to WhatsApp:
                value:
                  phone: '{mobile with country code}'
                  message_type: text
                  method: transaction
                  text: '{message text}'
                  tracking_data: '{tracking data}'
                  fallback_channel: whatsapp
                  fallback_whatsapp:
                    fallback_sender: '{sender id}'
                    fallback_username: '{whatsapp username}'
                    fallback_text: '{fallback message text}'
                    template_id: '{whatsapp template id}'
                    tm_id: '{tm id}'
                    pe_id: '{pe id}'
              Text with Fallback to SMS:
                value:
                  phone: '{mobile with country code}'
                  message_type: text
                  method: transaction
                  text: '{message text}'
                  tracking_data: '{tracking data}'
                  fallback_channel: sms
                  fallback_sms:
                    fallback_sender: '{sender id}'
                    fallback_username: '{sms username}'
                    fallback_text: '{fallback message text}'
                    template_id: '{sms template id}'
                    tm_id: '{tm id}'
                    pe_id: '{pe id}'
          application/xml:
            schema:
              type: object
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The status of the message delivery.
                  message:
                    type: string
                    description: The response message.
                  request_id:
                    type: string
                    description: A unique identifier for the request.
              examples:
                Successful API execution:
                  value:
                    status: success
                    message: Api execution is successful
                    request_id: 727591b0-e592-11ed-91d7-0242ac13xxxx
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/vbs_400_invalid_phone_number'
                - $ref: '#/components/schemas/vbs_400_invalid_text_msg'
                - $ref: '#/components/schemas/vbs_400_invalid_button_text'
                - $ref: '#/components/schemas/vbs_400_invalid_button_link'
                - $ref: '#/components/schemas/vbs_400_invalid_image_url'
                - $ref: '#/components/schemas/vbs_400_invalid_time_duration'
                - $ref: '#/components/schemas/vbs_400_incorrect_message_type'
                - $ref: '#/components/schemas/vbs_400_incorrect_message_method'
                - $ref: '#/components/schemas/vbs_400_invalid_thumbnail_url'
                - $ref: '#/components/schemas/vbs_400_unsupported_file_format'
                - $ref: '#/components/schemas/vbs_400_unsupported_video_file'
                - $ref: '#/components/schemas/vbs_400_campaign_short_name'
              examples:
                Invalid phone number:
                  value:
                    error:
                    - phone - Please provide valid phone no.
                Invalid text message:
                  value:
                    error:
                    - text - Length must be between 1 and 1000.
                Invalid button text:
                  value:
                    error:
                    - button_text - Length must be between 1 and 30.
                Invalid button link:
                  value:
                    error:
                    - button_link - Not a valid URL.
                Invalid image URL:
                  value:
                    error:
                    - img - Not a valid URL.
                Invalid time duration criteria:
                  value:
                    error:
                    - ttl - Must be greater than or equal to 30 and less than or equal to 1209600.
                Incorrect message type:
                  value:
                    status: failed
                    message: Api execution not successful
                    details: Please provide message type
                Incorrect message method:
                  value:
                    error:
                    - 'method - Must be one of: one_way, two_way, session.'
                Invalid thumbnail URL:
                  value:
                    error:
                    - thumbnail_url - Not a valid URL.
                Unsupported file format:
                  value:
                    error:
                    - file_url - File format not supported
                Unsupported video file format:
                  value:
                    error:
                    - video - Video format not supported
                Campaign name is too short:
                  value:
                    error:
                    - campaign_name - Shorter than minimum length 3.
        '401':
          description: Authentication Failure
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: Unauthorized access.
              examples:
                'Unauthorized ':
                  value:
                    response: Unauthorized
        '404':
          description: Page Not Found
          content:
            application/xml:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The message response.
              examples:
                Not found:
                  value: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <title>404 Not Found</title> <h1>Not Found</h1> <p>The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.</p>
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The error status.
                  message:
                    type: string
                    description: Rate limit exceeded message.
                  retry_after:
                    type: integer
                    description: Number of seconds to wait before retrying.
              examples:
                Rate limit exceeded:
                  value:
                    status: error
                    message: Too many requests. Please retry after the indicated time.
                    retry_after: 60
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The status of the message.
                  message:
                    type: string
                    description: The response message.
              examples:
                Server error:
                  value:
                    status: error
                    message: Unknown error occured while processing request
      security:
      - jwt: []
  /vbs/api/v2/manage-campaign:
    post:
      tags:
      - Viber Business Messaging API
      summary: Viber Send Campaign Messages APIs
      description: 'Viber Business Send Campaign Messages APIs allow businesses to send bulk campaign messages to multiple users on the Viber platform. A campaign uses a `file_code` returned from the Campaign File Upload API to address recipients.


        Here are the supported Viber Business Send Campaign Message types:


        - **Campaign Text:** Send a plain text message to multiple recipients.

        - **Campaign Text Button:** Send a text message with an action button to multiple recipients.

        - **Campaign Text Button Image:** Send a message with text, a button, and an image to multiple recipients.

        - **Campaign Text Image:** Send a message combining text and an image.

        - **Campaign Image:** Send a standalone image to multiple recipients.

        - **Campaign File:** Send a file/document attachment to multiple recipients.

        - **Campaign Video:** Send a video message to multiple recipients.

        - **Campaign Video Text:** Send a video with accompanying text to multiple recipients.

        - **Campaign Video Text Action Button:** Send a video with text and a structured action button to multiple recipients.

        - **Campaign Text Template:** Send a branded text message using an approved template to multiple recipients.

        - **Campaign with Fallback:** Send a Viber campaign with an automatic fallback to WhatsApp or SMS if recipients are unreachable on Viber.


        Optionally include `schedule_datetime` and `timezone` to schedule the campaign for a future send time.

        '
      operationId: campaignVideoText
      x-readme:
        samples-languages:
        - curl
        - python
        - node
        - java
        - php
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/vbs_campaign_text_button_image'
              - $ref: '#/components/schemas/vbs_campaign_text_button'
              - $ref: '#/components/schemas/vbs_campaign_text_msg'
              - $ref: '#/components/schemas/vbs_campaign_textimage_msg'
              - $ref: '#/components/schemas/vbs_campaign_image_msg'
              - $ref: '#/components/schemas/vbs_campaign_file_msg'
              - $ref: '#/components/schemas/vbs_campaign_video_msg'
              - $ref: '#/components/schemas/vbs_campaign_video_text_msg'
              - $ref: '#/components/schemas/vbs_campaign_video_text_action_button_msg'
              - $ref: '#/components/schemas/vbs_campaign_text_template_msg'
              - $ref: '#/components/schemas/vbs_campaign_fallback_msg'
            examples:
              Campaign Text Button Image:
                value:
                  campaign_id: '{campaign id generated post file upload}'
                  campaign_action: start
                  campaign_name: '{campaign name}'
                  ttl: '{time in seconds}'
                  file_mimetype: text/plain
                  filename: '{filename with extension}'
                  payload:
                    text: '{Message}'
                    button_text: '{button name}'
                    button_link: '{button url with https://}'
                    img: '{Public URL starting with http:// and ending with file extension}'
                    message_type: template
                    method: one_way/two_way
              Campaign Text Button:
                value:
                  campaign_id: '{campaign id generated post file upload}'
                  campaign_action: start
                  campaign_name: '{campaign name}'
                  ttl: '{time in seconds}'
                  file_mimetype: text/plain
                  filename: '{filename with extension}'
                  payload:
                    text: '{message}'
                    button_text: '{button name}}'
                    button_link: '{button url starting https://}'
                    message_type: media
                    method: one_way/two_way
              Campaign Text:
                value:
                  campaign_id: '{campaign id generated post file upload}'
                  campaign_action: start
                  campaign_name: '{campaign name}'
                  ttl: '{time in seconds}'
                  file_mimetype: text/plain
                  filename: '{filename with extension}'
                  payload:
                    text: '{message}'
                    button_text: '{button name}}'
                    button_link: '{button url starting https://}'
                    message_type: media
                    method: one_way/two_way
              Campaign Image:
                value:
                  campaign_id: '{campaign id generated post file upload}'
                  campaign_action: start
                  campaign_name: '{campaign name}'
                  ttl: '{time in seconds}'
                  file_mimetype: text/plain
                  filename: '{filename with extension}'
                  payload:
                    img: '{Public URL starting with http:// and ending with file extension}'
                    message_type: image
                    method: two_way/session
              Campaign File:
                value:
                  campaign_id: '{campaign id generated post file upload}'
                  campaign_action: start
                  campaign_name: '{campaign name}'
                  ttl: '{time in seconds}'
                  file_mimetype: text/plain
                  filename: '{filename with extension}'
                  payload:
                    file: '{Public URL starting with http:// and ending with file extension}'
                    message_type: file
                    method: two_way/session
              Campaign Video:
                value:
                  campaign_id: '{campaign id generated post file upload}'
                  campaign_action: start
                  campaign_name: '{campaign name}'
                  ttl: '{time in seconds}'
                  file_mimetype: text/plain
                  filename: '{filename with extension}'
                  payload:
                    video: '{Public URL starting with http:// and ending with file extension}'
                    message_type: video
                    thumbnail_url: '{image link with https:// with extension}'
                    method: two_way
              Campaign Video Text:
                value:
                  file_code: '{file code from upload}'
                  campaign_name: '{campaign name}'
                  personalised: false
                  payload:
                    message_type: text_video
                    method: promotion
                    video: '{video link with https:// with extension}'
                    text: '{body text}'
                    thumbnail_url: '{thumbnail image link with https:// with extension}'
              Campaign Text Image:
                value:
                  file_code: '{file code from upload}'
                  campaign_name: '{campaign name}'
                  personalised: false
                  payload:
                    message_type: text_image
                    method: promotion
                    img: '{image link with https:// with extension}'
                    text: '{body text}'
              Campaign Video Text Action Button:
                value:
                  file_code: '{file code from upload}'
                  campaign_name: '{campaign name}'
                  personalised: false
                  payload:
                    message_type: video_text_action_button
                    method: promotion
                    video: '{video link with https:// with extension}'
                    text: '{body text}'
                    thumbnail_url: '{thumbnail image link with https:// with extension}'
                    button:
                      button_url: '{button url with https://}'
                      button_text: '{button text}'
              Campaign Text Template:
                value:
                  file_code: '{file code from upload}'
                  campaign_name: '{campaign name}'
                  personalised: false
                  payload:
                    message_type: text_template
                    method: promotion
                    text: '{message text}'
                    tracking_data: '{tracking data}'
              Campaign with Fallback to SMS:
                value:
                  file_code: '{file code from upload}'
                  campaign_name: '{campaign name}'
                  personalised: false
                  payload:
                    message_type: image
                    method: promotion
                    img: '{image link with https:// with extension}'
                    fallback_channel: sms
                    fallback_sms:
                      fallback_sender: '{sender id}'
                      fallback_username: '{sms username}'
                      fallback_text: '{fallback message text}'
                      template_id: '{sms template id}'
                      tm_id: '{tm id}'
                      pe_id: '{pe id}'
              Campaign with Fallback to WhatsApp:
                value:
                  file_code: '{file code from upload}'
                  campaign_name: '{campaign name}'
                  personalised: false
                  payload:
                    message_type: image
                    method: promotion
                    img: '{image link with https:// with extension}'
                    fallback_channel: whatsapp
                    fallback_whatsapp:
                      fallback_sender: '{sender id}'
                      fallback_username: '{whatsapp username}'
                      fallback_text: '{fallback message text}'
                      template_id: '{whatsapp template id}'
                      tm_id: '{tm id}'
                      pe_id: '{pe id}'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The status of the campaign message delivery.
                  message:
                    type: string
                    description: The response message.
              examples:
                Campaign is in process:
                  value:
                    status: success
                    message: campaign with id ce078410-e593-11ed-9242-0242ac11xxxx is now processing
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/vbs_400_campaign_short_name'
                - $ref: '#/components/schemas/vbs_400_invalid_text_msg'
                - $ref: '#/components/schemas/vbs_400_invalid_button_text'
                - $ref: '#/components/schemas/vbs_400_invalid_time_duration'
                - $ref: '#/components/schemas/vbs_400_incorrect_message_type'
                - $ref: '#/components/schemas/vbs_400_incorrect_message_method'
                - $ref: '#/components/schemas/vbs_400_invalid_thumbnail_url'
              examples:
                Campaign name is too short:
                  value:
                    error:
                    - campaign_name - Shorter than minimum length 3.
                Invalid text message:
                  value:
                    error:
                    - text - Length must be between 1 and 1000.
                Invalid button text:
                  value:
                    error:
                    - button_text - Length must be between 1 and 30.
                Invalid time duration criteria:
                  value:
                    error:
                    - ttl - Must be greater than or equal to 30 and less than or equal to 1209600.
                Incorrect message type:
                  value:
                    status: failed
                    message: Api execution not successful
                    details: Please provide message type
                Incorrect message method:
                  value:
                    error:
                    - 'method - Must be one of: one_way, two_way, session.'
                'Invalid thumbnail URL ':
                  value:
                    error:
                    - thumbnail_url - Not a valid URL.
        '401':
          description: Authentication Failure
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: The response message.
              examples:
                Unauthorized:
                  value:
                    response: Unauthorized
        '404':
          description: Page Not Found
          content:
            application/xml:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The message response.
              examples:
                Not found:
                  value: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <title>404 Not Found</title> <h1>Not Found</h1> <p>The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.</p>
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The error status.
                  message:
                    type: string
                    description: Rate limit exceeded message.
                  retry_after:
                    type: integer
                    description: Number of seconds to wait before retrying.
              examples:
                Rate limit exceeded:
                  value:
                    status: error
                    message: Too many requests. Please retry after the indicated time.
                    retry_after: 60
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The status of the send campaign message.
                  message:
                    type: string
                    description: The response message.
              examples:
                Server error:
                  value:
                    status: error
                    message: Unknown error occured while processing request
      security:
      - jwt: []
  /vbs/api/v2/upload:
    post:
      tags:
      - Viber Business Messaging API
      summary: Campaign File Upload
      description: 'The Campaign File Upload API allows businesses to securely upload their contact list or campaign content files to Viber''s platform for use in bulk campaigns.


        Files must be uploaded as binary data using `multipart/form-data`. The following file formats are supported:

        - **CSV** (`.csv`) — Comma-separated contact list

        - **Excel** (`.xlsx`, `.xls`) — Spreadsheet contact list

        - **Plain Text** (`.txt`) — Tab or newline-delimited contact list

        - **ZIP** (`.zip`) — Archive containing a single CSV file


        Once uploaded, the API returns a `campaign_id` which is required when sending campaign messages via the Send Campaign Messages API.'
      operationId: campaignFileUpload
      x-readme:
        samples-languages:
        - curl
        - python
        - node
        - java
        - php
      requestBody:
        required: true
        description: 'Upload a campaign contact list or content file as a binary multipart/form-data request. Supported formats: CSV, XLSX, XLS, TXT, and ZIP (containing CSV). For sample file formats, see:

          - [Bulk Upload File](https://github.com/routemobile/Viber-Business-Messages-API/blob/master/Sample%20Bulk%20Upload%20File.txt)

          - [Bulk Upload Campaign File](https://github.com/routemobile/Viber-B

# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/route-mobile/refs/heads/main/openapi/route-mobile-viber-business-messaging-api-api-openapi.yml