Route Mobile Viber Business Messages API

openapi: 3.0.0
info:
  version: 1.5.0
  title: Route Mobile Viber OpenAPI Specification
  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
x-logo:
  url: https://routemobile.github.io/Viber-Business-Messages-API/Logo.png
  backgroundColor: '#FFFFFF'
  altText: RouteMobile logo
security:
- jwt: []
servers:
- url: https://apis.rmlconnect.net
- url: '{client callback}'
paths:
  /callback:
    post:
      tags:
      - Viber Client Callback API
      summary: Viber Client Callback
      description: Viber Client Callback APIs allow you to receive real-time notifications for events
        that occur on your Viber Business Messaging account. These callbacks are triggered by events that
        occur on the Viber server, and are delivered to a URL that you specify in your webhook configuration.
      operationId: viberClientCallback
      x-readme:
        samples-languages:
        - curl
        - python
        - node
        - java
        - php
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/vbs_callback_incoming_text'
              - $ref: '#/components/schemas/vbs_callback_incoming_videoimage'
              - $ref: '#/components/schemas/vbs_callback_delivery_report'
            examples:
              Incoming Text:
                value:
                  phone_number: '{phone}'
                  time: 2121212121
                  message:
                    text: a message to the sender
                    tracking_data: tracking_id:100xxx5
                  service_type: two_way/session
                  request_id: 70d9758e-70ef-11eb-b813-a81e84xxxxxx
              Incoming Image/video:
                value:
                  phone_number: '{phone number with country code}'
                  time: 1622014595
                  message:
                    tracking_data: '{tracking id}'
                    media: '{media url}'
                    file_name: '{filename with extension}'
                  service_type: two_way/session
                  request_id: 1a761762-bdf5-11eb-aa2f-0242acxxxxxx
              Delivery Report - Delivered:
                value:
                  message_status: delivered
                  message_time: 1767762961213
                  phone_number: '{phone number with country code}'
                  service_type: dlr
                  request_id: f33647ec-eb87-11f0-aa5a-0242acxxxxxx
              Delivery Report - Sent:
                value:
                  session_id: null
                  request_id: f33647ec-eb87-11f0-aa5a-0242acxxxxxx
                  message_status: Sent
                  message_time: 1767762958
                  phone_number: '{phone number with country code}'
                  matching_template_id: null
                  service_type: dlr
              Delivery Report - Seen:
                value:
                  message_status: seen
                  message_time: 1767763013183
                  phone_number: '{phone number with country code}'
                  service_type: dlr
                  request_id: f33647ec-eb87-11f0-aa5a-0242acxxxxxx
              Delivery Report - Expired:
                value:
                  message_status: expired
                  message_time: 1767763626948
                  phone_number: '{phone number with country code}'
                  service_type: dlr
                  request_id: 818249f0-eb89-11f0-ba44-0242acxxxxxx
      responses:
        '200':
          description: Success
        '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
      security: []
  /auth/v1/login/:
    post:
      tags:
      - Viber Login
      summary: Login API
      description: |-
        Login APIs provide a secure and standardized way for end users to add user authentication to their applications. Only authorized users can access sensitive resources or perform specific actions within the application after entering the user authentication details.

        **By default, the JSON Web Token (JWT) validity periods are set to one hour.**
      operationId: loginApi2
      x-readme:
        samples-languages:
        - curl
        - python
        - node
        - java
        - php
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1_login_body'
            examples:
              Example 1:
                value:
                  password: password
                  username: username
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_201_2'
              examples:
                Authentication successful:
                  value:
                    JWTAUTH: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZGVtbyIsInVzZXJuYW1lIjoiZGVtbyIsImV4cCI6MTY4Mzg4OTI0MSwiZW1haWwiOiJwcm9kdxxxxxxxxxxAcm91dGVtb2JpbGUuY29tIiwib3JpZ19pYXQiOjE2ODM4ODU2NDEsImN1c3RvbWVyX2lkIjoiOWlyNURnN2J2c0NBIn0.gu2LO-bDVPqa35v_MnyO1KKeZzhxxxxxxxxxxxxxxxx
                    user_data:
                      username: demo
                      first_name: user
                      last_name: name
                      email: user_name@orgdomain.com
                      phone_number: '{phone}'
                      password_reset: false
                      is_active: true
                      is_staff: false
                      ip: 1stepauxx
                      child_user: false
                      parent_username: ''
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The user login status.
              examples:
                User is set inactive:
                  value:
                    status: invalid credentials or the account has been deactivated
        '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 user login status.
              examples:
                Unhandled Exception:
                  value:
                    status: <exception>
      security: []
  /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
                   

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