Viber API Documentation7.3.0

Docs / Tools / Channels Post API

Channels Post API

Get ready to automatically post your content to an unlimited audience! Using the API described below you can configure your system to post directly into your Viber Channel.Get started now

Prerequisites

  1. Own a Channel – only Channel super admins can get access to API.

  2. Must be using a version of Viber 17.7 or higher.

  3. Obtain Authentication token.

In order to implement our API, as a channel super admin you will need to obtain an authentication token unique for your Channel. You can do this by entering your Channel’s info screen-> scroll down to “Developer Tools” -> copy token -> use the token for posting via API.

Setting a webhook

Once you have your token you will be able to set your Channel’s webhook. To send messages using this API, it is necessary to set a webhook.

Setting the webhook will be done by calling the set_webhook API with a valid and certified URL. For security reasons only URLs with valid and official SSL certificate from a trusted Certificate Authority will be allowed. This action defines the account’s webhook and the type of events the account wants to be notified about.

Once a set_webhook request is sent Viber will send a callback to the webhook to check its availability. The webhook must reply with status 200 for the request to succeed.

Please Note: Posting to the Channel using the API, or when new messages are posted in the Channel by users will not generate a callback to this webhook.

Destination URL for set_webhook POST request

https://chatapi.viber.com/pa/set_webhook

Post data

{
   "url":"https://my.host.com",
   "auth_token":"your_auth_token"
}

Post parameters

Name Description Validation
url Required. Account webhook URL to receive callbacks & messages from users Webhook URL must use SSL. Note: Viber doesn’t support self signed certificates

Set webhook Response

{ 
   "status":0, 
   "status_message":"ok", 
   "event_types":[ 
      "delivered", 
      "seen", 
      "failed", 
      "subscribed", 
      "unsubscribed", 
      "conversation_started" 
   ] 
}

event_types are deprecated, please ignore

Response parameters

Name Description Validation
status Action result 0 for success. In case of failure – appropriate failure status number. See error codes table for additional information
status_message ok or failure reason Success: ok. Failure: invalidUrl, invalidAuthToken , badData , missingData and failure . See error codes table for additional information

Set webhook callback

For each set_webhook request Viber will send a callback to the webhook URL to confirm it is available. The expected HTTP response to the callback is 200 OK – any other response will mean the webhook request failed. If the webhook is not available the set_webhook response will be status 1: invalidUrl.

Callback data

{ 
   "event":"webhook", 
   "timestamp":1457764197627, 
   "message_token":241256543215 
}

Callback parameters

Name Description Validation
event Callback type – which event triggered the callback webhook
timestamp Time of the event that triggered the callback Epoch time
message_token Unique ID of the message  

Get Account Info

The get_account_info request will fetch the account’s details as registered in Viber. The account admin will be able to edit most of these details from his Viber client.

The Sender IDs of the Channel superadmins (role “superadmin”) and admins (role “admin”) can be found under the “members” field of the response. Only the superadmins’ ID should be used as the sender ID with this API.

Destination:

https://chatapi.viber.com/pa/get_account_info

Post data

{
   "auth_token":"your_auth_token"
}

Response

{
	"status":0,
	"status_message":"ok",
	"Id":"pa:75346594275468546724",
	"chat_hostname":"Channel name",
	"background":"https://content.cdn.viber.com/backgrounds_v1/Android/800/10000501.jpg",
	"members":[
		{
		"id":"01234567890A=",
		"name": "my name",
		"avatar" :"https://example.com",
		"role":"admin"
		}
	]
}

Sending a message

In order to post to your Channel you will need to send a POST request with the below properties.

Destination URL

https://chatapi.viber.com/pa/post

General send message parameters

The following parameters are available for all message types:

Name Description Validation
from Unique Viber user id Required, valid user id. Your audience will see the sender’s name as the Channel name. Note that Channels Super admins uses Channel name alias by default, you can change this in your Channel settings panel
type Message type Required. Available message types: text, picture, video, file, location, contact, sticker, url

Please Note: All requests should be in JSON format.

Message types

Below is a list of all supported message types with post data examples.

Text message

Post data

{
    "auth_token":"your_auth_token", 
    "from":"your_user_id", 
    "type":"text", 
    "text":"Hello world!" 
}

Post parameters

Name Description Validation
type Message type required.text
text The text of the message required. Max 7000 characters

Picture message

Post data

{  
   "auth_token":"your_auth_token", 
   "from":"your_user_id", 
   "type":"picture", 
   "text":"Picture description", 
   "media":"https://www.images.com/img.jpg", 
   "thumbnail":"https://www.images.com/thumb.jpg" 
}

Post parameters

Name Description Validation
type Message type required.picture
text Description of the photo. Can be an empty string if irrelevant Required. Max 768 characters
media URL of the image (JPEG) Required. Max size 1 MB. Only JPEG format is supported. Other image formats as well as animated GIFs can be sent as URL messages or file messages. The URL must have a resource with a .jpeg file extension. Example: https://www.example.com/path/image.jpeg
thumbnail URL of a reduced size image (JPEG) Optional. Max size 100 kb. Recommended: 400x400. Only JPEG format is supported

Video message

Post data

{  
   "auth_token":"your_auth_token", 
   "from":"your_user_id", 
   "type":"video", 
   "media":"https://www.images.com/video.mp4", 
   "thumbnail":"https://www.images.com/thumb.jpg", 
   "size":10000, 
   "duration":10 
}

Post parameters

Name Description Validation
type Message type required.video
media URL of the video (MP4, H264) Required. Max size 50 MB. Only MP4 and H264 are supported
size Size of the video in bytes Required
duration Video duration in seconds; will be displayed to the receiver Optional. Max 180 seconds
thumbnail URL of a reduced size image (JPEG) Optional. Max size 100 kb. Recommended: 400x400. Only JPEG format is supported

File message

Post data

{  
   "auth_token":"your_auth_token", 
   "from":"your_user_id", 
   "type":"file", 
   "media":"https://www.images.com/file.doc", 
   "size":10000, 
   "file_name":"name_of_file.doc" 
}

Post parameters

Name Description Validation
type Message type required.file
media URL of the file Required. Max size 50 MB. See forbidden file formats for unsupported file types
size Size of the file in bytes Required
file_name Name of the file Required. File name should include extension. Max 256 characters (including file extension). Sending a file without extension or with the wrong extension might cause the client to be unable to open the file

Contact message

Post data

{ 
   "auth_token":"your_auth_token", 
   "from":"your_user_id", 
   "type":"contact", 
   "contact":{ 
      "name":"John Doe", 
      "phone_number":"+12025550164" 
   } 
}

Post parameters

Name Description Validation
type Message type required.contact
contact.name Name of the contact Required. Max 28 characters
contact.phone_number Phone number of the contact Required. Max 18 characters

Location message

Post data

{ 
   "auth_token":"your_auth_token", 
   "from":"your_user_id", 
   "type":"location", 
   "location":{ 
      "lat":"37.7898", 
      "lon":"-122.3942" 
   } 
}

Post parameters

Name Description Validation
type Message type required.location
location Location coordinates Required. Latitude (±90°) and longitude (±180°) within valid ranges

URL message

Post data

{ 
   "auth_token":"your_auth_token",
   "from":"your_user_id",
   "type":"url",
   "text":"optional text to describe the URL",
   "media":"https://www.website.com/go_here"
}

Post parameters

Name Description Validation
type Message type required.url
media URL Required. Max 2,000 characters
text Description of the URL Optional. Max 120 characters

Sticker message

Post data

{ 
   "auth_token":"your_auth_token", 
   "from":"your_user_id",  
   "type":"sticker", 
   "sticker_id":46105 
}

Post parameters

Name Description Validation
type Message type required.sticker
sticker_id URL Unique Viber sticker ID. For examples visit the sticker IDs page

Error Codes

The following error codes will be returned with API responses. The status parameter will include the error code value while the status_message parameter will include the error name or a more specific string describing the error.

Value Name Description
0 ok Success
1 invalidUrl The webhook URL is not valid
2 invalidAuthToken The authentication token is not valid
3 badData There is an error in the request itself (missing comma, brackets, etc.)
4 missingData Some mandatory data is missing
7 publicAccountBlocked The account is blocked
8 publicAccountNotFound The account associated with the token is not a account.
9 publicAccountSuspended The account is suspended
10 webhookNotSet No webhook was set for the account
12 tooManyRequests Rate control breach
other General error General error

Refresh a token

In the event that you need to invalidate the current authentication token and generate a new one, please email your request to devsupport@viber.com with the link to the Channel & the super admin’s phone number.