Viber Business | Send & Receive Messages

Hi there!

So you have set up your Viber Business service with tyntec -- congrats! You can now implement sending and receiving of Viber messages in your app.

You will need

  • A tyntec API key from your tyntec account to authorize your requests

  • A Viber Service ID, which works like a phone number for Viber Business

Send a message

To send Viber messages, you make HTTP requests to the tyntec’s Conversations API.

 

​​​​​​Set headers

Authorize your API calls by adding the HTTP header apikey with your API key that you’ve got from your Business Center.

The REST API accepts data in the JSON format (Content-Type: application/json) and responds with JSON data as well (Accept: application/json). Setting these headers is optional, however, you need to set them if your HTTP client has other defaults.

The complete headers look like this:

Content-Type: application/json
Accept: application/json
apikey: YOUR_API_KEY

Send a text message

To send a simple Viber text message, you should provide a recipient phone number (to), specify the channel and channel-specific data, such as your Service ID (from) and the text component of the message with content.

The rateType controls the charging by Viber and the available message types.

The simplest request with only required parameters looks as follows:

POST https://api.tyntec.com/conversations/v3/messages
{    
  "to": {{receiverPhoneNumber}}",
   "channel" : "viber",
  "from": "{{viberServiceId}}",
  "rateType": "transaction|promotion|session",
  "content": {     
        "type": "text", 
        "text": "Hello world!"
  }
}

The initial response is synchronous and contains the ID of your message. This ID is valid for 48 hours if you want to retrieve the message and 90 days for status and history. If you received status 202, then you know your message was accepted for sending.

{     
  "messageId": "8fb360a1-f58c-4af1-932b-8f6651603cd4" 
}

Poll for delivery status

If you want to see the delivery status of your message, use the following HTTP GET request:

GET https://api.tyntec.com/conversations/v3/{messageId}/status

The response JSON contains status, deliveryChannel and timestamp. For example:

{
  "messageId": "1697383a-f16d-4c91-9b75-2b5ee650b9a3",
  "deliveryChannel": "viber",
  "status": "delivered",
  "timestamp": "2020-07-13T13:02:53.704Z"
}

Send a message with media

Using tyntec's API you can send more than simple text, it supports images and buttons. If you want to send an image, change the components to following:

POST https://api.tyntec.com/conversations/v3/messages
{
    "from" : "SERVICE_ID",
    "to" : "{{viberServiceId}}",
    "channel" : "viber",
    "messagePurpose": "transaction|promotion",
    "content" : {
        "contentType" : "image",
        "image" : {
            "url": "https://upload.wikimedia.org/wikipedia/commons/6/6c/Sample_EPC_QR_code.png"
        }
    }
}

The response is the same as with a text message and you can also check the delivery status the same way as mentioned above.

Receive a message

tyntec delivers messages from your customers via callbacks to your webhook URL.

Tip: You may use our webhook-starter written in Node.js and ngrok tunneling for development and testing.

To let tyntec know about your webhook URL, you need to update application information using a HTTP PATCH request to the default application endpoint like this:

PUT https://api.tyntec.com/conversations/v3/configurations/callbacks
{
        "callbackVersion": "2.11",
        "inboundMessageUrl": "<your server>",
        "messageStatusUrl": "<your server>",        
        "eventFilter": [
            "InboundMessage"
        ]
    }

If you’ve received a 204 status in a response, tyntec knows now that messages shall be delivered to that URL.

Tip: You can use our Postman collection (together with the Postman platform). Just unzip it, import the files, and use requests from the Application Management folder.

A callback request from tyntec looks like this:

{
  "messageId": "5463481551745434076",
  "channel": "viber",
  "from": "123456789",
  "to": "VIBER_ID",
  "receivedAt": "2020-07-13T15:14:44Z",
  "content": {
    "contentType": "text",
    "text": "Hi!"
  },
  "event":"MoMessage",
  "timestamp":"2020-07-13T15:14:44Z"
}

Ooops… trouble?

If your message has issues with delivery, there are few things you can do before contacting our support team. It is usually a good idea to re-test, whether a problem occurs on more phone numbers. You can also retrieve your message to check if all parameters are correct. Go back to send a message for check or look at our API reference.

If this doesn't help, note the messageId. Our support team will appreciate it if you also add message history to your new ticket.

Retrieve a sent message

If you want to see details of your message, you can poll info through API using the following HTTP GET request:

GET https://api.tyntec.com/conversations/v3/messages/{messageId}

The response is of the StoredMessage schema, which looks as follows:

{
  "to": "123456789",     
  "id": "8fb360a1-f58c-4af1-932b-8f6651603cd4",    
  "channels": ["viber"], 
  "viber": { 
    "from": "SERVICE_ID",
    "components": [
      { 
         "type": "text",
         "text": "Your message"
      }
    ], 
    "messagePurpose": "promotion", 
    "contentType": "text"    
  }
}

Retrieve delivery events

To see the message status, you need to poll info through API with the following HTTP GET request:

GET https://api.tyntec.com/conversations/v3{messageId}/events

The response displays the route of your message. You can see that it goes through 4 “nodes”. The following response shows a successful delivery.

{     
  "messageId": "8fb360a1-f58c-4af1-932b-8f6651603cd4",     
  "history": [
    {
      "happendAt": "2020-07-13T12:19:17.606Z",
      "state": "message-accepted"
    },
    {
      "deliveryChannel": "viber",
      "happendAt": "2020-07-13T12:19:17.644Z",
      "state": "message-routing-success"
    }, 
    {
      "deliveryChannel": "viber",
      "happendAt": "2020-07-13T12:19:17.781Z",
      "state": "message-dispatching-success"
    },
    {
      "deliveryChannel": "viber",
      "happendAt": "2020-07-13T12:19:18.967Z",
      "state": "message-delivered",
      "details": { 
        "from": "123456789"
      } 
  }]
}