Thank you for filling out the form. One of our mobile experts will be in touch shortly to discuss your inquiry.
If you have any other questions please feel free to email us directly at info@mitto.ch
SMS Failover
Overview
Provider for SMS is Mitto HTTP API.
Send SMS
For sending, we use common endpoint POST /message/send
{
"trafficAccountId": "4ae53d46-66d8-4aff-9f13-621f53b9xxxx",
"destination": "+0123456789",
"sms":{
"text": "Hi, this is test msg.",
"sender": "+44123456789123"
}
}
All fields are the same as for other channels, except “SENDER”, which must be one of following:
numeric (1-16 characters)
alphanumeric (1-11 characters)
Prior to sending to Mitto HTTP API, ChatApps generates a token for each message, which is provided in callback URL, and used later to validate that callback. Token lifetime can be set in the configuration. Example of message send request from ChatApps to Mitto HTTP API:
{
"from": "+4412345678xxx",
"to": "385911234xxxx",
"text": "Hi, this is test msg.",
"callback": "https://webhook.site/1126dbd2-23ef-48db-b861-
4ef63c1812e3?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE2MjIxMTE4NjcsImV4cCI6MTYyMjE
I7j33HVp2kWSs-_LelLYyv4EMNEK8YuI753SQnd5sA"
}
Callbacks
DLR
Every DLR callback must-have content-type application/JSON., and the following format:
{
"messageId":"~msgid~",
"status":"~status~",
"errorcode":"~errorcode~"
}
Inbound SMS (2 way)
For inbound SMS, there has to be an SMS number on the Mitto side that is configured for 2-way, and callbacks set to ChatApps callback URL.
Tokens validation and key rotation
Both keys for signing/validating tokens for DLR and inbound messages, are set in-app settings (env variables), and support multiple values, to allow key rotation.
Google’s Business Messages
Send Google’s Business Messages
With Business Messages, you can place messaging buttons for brands within organic Google search results. When a user clicks on a messaging button, they start a conversation with an entity representing the brand—the brand’s agent.
The conversation takes place on a Google messaging surface available on iOS and Android. You receive and respond to customer messages, through the agent, using a webhook and the Business Messages API.
Representative
Details about the representative (human or chatbot) that sent the message.
Representative type
| Parameter | Description |
| BOT | Bot representative. |
| HUMAN | Human representative. |
{
...
"gbm":{
...
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Fallback strategy
If a user’s device doesn’t support a message you attempt to send, such as if a user doesn’t support suggested replies, the API returns a 400 (FAILED PRECONDITION) error. However, you can work around unsupported message types by specifying fallback text for each message you send. If you specify fallback text, the API returns a 200 OK response, even if the user’s device doesn’t support the message type.
If a user receives a message that their device doesn’t support but includes fallback text, their device displays the fallback text instead. This behavior allows you to continue the conversation in a proactive way without interrupting the conversation’s flow or taking extra time to process a 400 (FAILED PRECONDITION) error and identifying an alternate message.
fallback text for any given message should mirror the function of the message. For example,
- For messages with suggested replies or actions, include the message text in the fallback text, and include guidance on what options users have to continue the conversation.
- For rich cards or carousels, include the title and description in the fallback text, and include links to images or websites.
To insert line breaks in fallback text, use \n or \r\n.
Test fallback text
Before you launch an agent, you can test how fallback text appears in a conversation by sending a message with the parameter forceFallback set to true. When you force fallback text, the conversation disregards the main image in the following example, and displays the fallback text instead.
{
"trafficAccountId": "9dbe5291-6292-48ad-8aab-6383d8f7xxxx",
"destination": "bb8ceef0-90b4-4876-9467-c8c9ecc1c4e0",
"gbm": {
"forceFallback": true,
"fallback": "This is just a fallback message, the image part is ignored. The purpose of this message is to have some feedback even on devices which does not support media content.",
"image": {
"fileUrl": "https://file-examplescom.github.io/uploads/2017/10/file_example_JPG_100kB.jpg",
"thumbnailUrl": "https://picsum.photos/200/300?random=1",
"forceRefresh": true,
"altText": "alternative text for image"
},
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Text (URL) Only
The simplest messages are made of text. Text messages are best suited to communicate information without the need for visuals, complex interaction, or response.
REQUEST: POST /messages/send
{
"trafficAccountId": "9dbe5291-6292-48ad-8aab-6383d8f7xxxx",
"destination": "bb8ceef0-90b4-4876-9467-c8c9ecc1c4e0",
"gbm":{
"text": {
"message":"Hi, this is test message."
},
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Send URL
{
...
"gbm":{
"text": {
"message":"https://mitto.ch"
},
...
}
}
Rich text
Note: This feature is for messages only, it isn’t supported in welcome messages, suggested replies, suggested actions, or rich cards.
Text messages with containsRichText set to true may include basic Markdown formatting. You can include hyperlinks or make text bold or italics. (see: https://developers.google.com/businesscommunications/business-messages/guides/build/send#rich_text)
REQUEST: POST /messages/send
{
"trafficAccountId": "9dbe5291-6292-48ad-8aab-6383d8f7xxxx",
"destination": "bb8ceef0-90b4-4876-9467-c8c9ecc1c4e0",
"gbm": {
"text": {
"message":"Hi, this is test message. **bold** Visit: [Click here](https://mitto.ch)",
"containsRichText": true
},
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Images
Send an image to a user in a message.
You can send an image message with URLs to the image and the image thumbnail.
REQUEST: POST /messages/send
{
"trafficAccountId": "9dbe5291-6292-48ad-8aab-6383d8f7xxxx",
"destination": "bb8ceef0-90b4-4876-9467-c8c9ecc1c4e0",
"gbm":{
"image": {
"fileUrl": "https://picsum.photos/1920/1080?random=1",
"thumbnailUrl": "https://picsum.photos/200?random=1",
"forceRefresh": true,
"altText": "alternative text for image"
},
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Suggested replies
Suggested replies guide users through conversations by providing responses that your agent knows how to react to.
When a user taps a suggested reply, your agent receives a message that contains the reply’s text and postback data.
Suggested replies have a maximum of 25 characters, and a message has a maximum of 13 suggestions.
REQUEST: POST /messages/send
{
"trafficAccountId": "9dbe5291-6292-48ad-8aab-6383d8f7xxxx",
"destination": "bb8ceef0-90b4-4876-9467-c8c9ecc1c4e0",
"gbm": {
"text": {
"containsRichText": true,
"message":"Trying **replies**!"
},
"suggestions": [
{
"reply": {
"text": "Reply one",
"postbackData": "hello-reply-1"
}
},
{
"reply": {
"text": "Reply two",
"postbackData": "hello-reply-2"
}
},
{
"reply": {
"text": "Reply three",
"postbackData": "hello-reply-3"
}
}
],
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Suggested actions
Suggested actions guide users through conversations by leveraging the native functionality of the their devices. When a user taps a suggested action, your agent receives a message that contains the action’s text and postback data.
Suggested actions have a maximum of 25 characters, and a message has a maximum of 13 suggestions.
Open URL action
With the Open URL action, your agent suggests a URL for a user to open. If an app is registered as a default handler for the URL, the app opens instead, and the icon for the action is the app’s icon.
Standalone card
When you need to send a chunk of related information, media, or suggestions, you should send a card. Cards allow your agent to send multiple units of information in a single message.
A card can contain the following items:
- Media (JPG, JPEG, or PNG, maximum 5 MB)
- Media thumbnail (JPG, JPEG or PNG, maximum 25 KB)
- Title (maximum 200 characters)
- Description (maximum 2000 characters)
- A list of suggested replies and suggested actions (maximum 4)
A card can contain any or all of the listed items, but a card must contain at least media or a title to be valid. A rich card can contain a maximum of four suggested actions and suggested replies.
Card height
Cards expand vertically to fit their contents. Rich cards have a minimum height of 112 DP and a maximum height of 344 DP. If the contents of a card are not large enough to fill the minimum card height, the card expands and fills the extra height with white space.
Media in rich cards must fit one of three heights:
- Short: 112 DP
- Medium: 168 DP
- Tall: 264 DP
If the media doesn’t fit the dimensions within the card given the selected height, the media preview is chosen by zooming and cropping the media.
Media height
| Parameter | Description |
| SHORT | 112 DP. |
| MEDIUM | 168 DP. |
| TALL | 264 DP. Not available for rich card carousels when the card width is set to SMALL. |
REQUEST: POST /messages/send
{
"trafficAccountId": "9dbe5291-6292-48ad-8aab-6383d8f7xxxx",
"destination": "bb8ceef0-90b4-4876-9467-c8c9ecc1c4e0",
"gbm": {
"standaloneCard": {
"title": "card 1",
"description": "This is a card",
"media": {
"height": "SHORT",
"contentInfo": {
"fileUrl": "https://picsum.photos/1920/1080?random=1",
"thumbnailUrl": "https://picsum.photos/200?random=1",
"altText": "alternative text for card image"
}
}
},
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Standalone card + Suggestions
You can combine cards with suggestions (see: Suggested replies and Suggested actions)
REQUEST: POST /messages/send
{
"trafficAccountId": "9dbe5291-6292-48ad-8aab-6383d8f7xxxx",
"destination": "bb8ceef0-90b4-4876-9467-c8c9ecc1c4e0",
"gbm": {
"standaloneCard": {
"title": "card 1",
"description": "This is a card",
"media": {
"height": "SHORT",
"contentInfo": {
"fileUrl": "https://picsum.photos/1920/1080?random=1",
"thumbnailUrl": "https://picsum.photos/200?random=1",
"altText": "alternative text for card image"
}
},
"suggestions": [
{
"reply": {
"text": "Hello",
"postbackData": "hello-formal"
}
},
{
"reply": {
"text": "Hi!",
"postbackData": "hello-informal"
}
}
]
},
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Card carousels
When you need to present a user with multiple options to choose between, use a card carousel.
Carousels string together multiple cards, allowing users to compare items and react to each individually.
Carousels may contain a minimum of two and a maximum of ten cards. Cards within carousels must conform to general card requirements for content and height.
The width of the cards in the carousel.
| Parameter | Description |
| SMALL | 136 DP. Can’t include tall media. |
| MEDIUM | 280 DP. |
REQUEST: POST /messages/send
{
"trafficAccountId": "9dbe5291-6292-48ad-8aab-6383d8f7xxxx",
"destination": "bb8ceef0-90b4-4876-9467-c8c9ecc1c4e0",
"gbm": {
"carouselCard": {
"cardWidth": "SMALL",
"cardContents": [
{
"title": "card 1",
"description": "This is a card 1",
"media": {
"height": "SHORT",
"contentInfo": {
"fileUrl": "https://picsum.photos/1920/1080?random=1",
"altText": "alternative text for card1 image"
}
}
},
{
"title": "card 2",
"description": "This is a card 2",
"media": {
"height": "SHORT",
"contentInfo": {
"fileUrl": "https://picsum.photos/1920/1080?random=2",
"altText": "alternative text for card2 image"
}
}
},
{
"title": "card 3",
"description": "This is a card 3",
"media": {
"height": "SHORT",
"contentInfo": {
"fileUrl": "https://picsum.photos/1920/1080?random=3",
"altText": "alternative text for card3 image"
}
}
},
{
"title": "card 4",
"description": "This is a card 4",
"media": {
"height": "SHORT",
"contentInfo": {
"fileUrl": "https://picsum.photos/1920/1080?random=4",
"altText": "alternative text for card4 image"
}
}
},
{
"title": "card 5",
"description": "This is a card 5",
"media": {
"height": "SHORT",
"contentInfo": {
"fileUrl": "https://picsum.photos/1920/1080?random=5",
"altText": "alternative text for card5 image"
}
}
},
{
"title": "card 6",
"description": "This is a card 6",
"media": {
"height": "SHORT",
"contentInfo": {
"fileUrl": "https://picsum.photos/1920/1080?random=6",
"altText": "alternative text for card6 image"
}
}
}
]
},
"representative": {
"avatarImage": "https://www.w3schools.com/howto/img_avatar.png",
"displayName": "Mark Marcus",
"representativeType": "HUMAN"
}
}
}
Viber Bot
Send Viber Bot message
Get Started
To implement the API, you will need the following:
- An Active Viber account on a platform which supports bots (iOS/Android). This account will automatically be set as the account administrator during the account creation process.
- Active bot – Create a bot here.
- Account authentication token – unique account identifier used to validate your account in all API requests. Once your account is created your authentication token will appear in the account’s “edit info” screen (for admins only). Each request posted to Viber by the account will need to contain the token.
- Setup account webhook – this needs to be done once during the account setup process to define your webhook and the type of responses you would like to receive. In order to implement the API you will need the following:
Authentication token
The authentication token (also known as the application key) is a unique and secret account identifier. It is used to authenticate requests in the Viber API and to prevent unauthorized persons from sending requests on behalf of a bot.
The authentication token is generated upon bot creation and can be viewed by the account’s admins in the “edit info” screen of their bot or on the Viber Admin Panel.
Send Message
The API allows accounts to send messages to Viber users who subscribe to the account. Sending a message to a user will be possible only after the user has subscribed to the bot. (see subscribed callback for additional information). You can share your bot with the users via a deeplink.
The API supports a variety of message
types: text, picture, video, file, location, sticker, contact, carousel content and URL.
Specific post data examples and required parameters for each message type are given below.
Text Only
REQUEST: POST /messages/send
type: session, promotional, transactional
{
"trafficAccountId": "fea74b75-8b26-4cef-8d79-162ceaef2056",
"destination": "{{phone-number}}",
"viber": {
// type: promotional,transactional
"type":"transactional",
"text":"Hi, how can I help you today?"
}
}
Image Only
REQUEST: POST /messages/send
type: session, promotional
{
"trafficAccountId": "fea74b75-8b26-4cef-8d79-162ceaef2056",
"destination": "{{phone-number}}",
"viber": {
// type: promotional
"type":"promotional",
"mediaUrl": "https://www.gstatic.com/webp/gallery3/1.png"
}
}
Text & Action Button
The “action” field can be any valid URL or one of Viber’s URL Schemes (see: URL Schemas)
REQUEST: POST /messages/send
type: promotional
{
"trafficAccountId": "fea74b75-8b26-4cef-8d79-162ceaef2056",
"destination": "{{phone-number}}",
"viber": {
// type: promotional
"type": "promotional",
"ttl": 90,
"text": "Hi, how can I help you today?",
"button": {
"caption": "Scan!",
"action": "viber://more/qr"
}
}
Text, Image & Action Button
REQUEST: POST /messages/send
type: promotional
{
"trafficAccountId": "fea74b75-8b26-4cef-8d79-162ceaefxxxx",
"destination": "{{phone-number}}",
"viber": {
// type: promotional
"type": "promotional",
"mediaUrl": "https://www.gstatic.com/webp/gallery3/1.png",
"text": "Hi, how can I help you today?",
"button": {
"caption": "QR Scan",
"action": "viber://other/scan"
}
}
}
File Transfer
You can send and receive files as long as they are on the following list of supported formats and under 200MB.
| File Type | File Formats | File Max Size |
| Documents | .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt,.txt, .info | 200 MB |
| .pdf, .xps, .pdax, .eps | ||
| Spreadsheet | .xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx |
The filename is optional however if it is not given the system will try to determine from the URL, if that is not possible (e.g., it does not contain any sane filename), then the filename is required. Filename – maximum 25 characters.
REQUEST: POST /messages/send
type: type: session, promotional
{
"trafficAccountId": "fea74b75-8b26-4cef-8d79-162ceaef2056",
"destination": "{{phone-number}}",
"viber": {
// type: promotional
"type": "promotional",
"file": {
"mediaUrl": "https://file-examples-com.github.io/uploads/2017/10/file-sample_150kB.pdf",
"fileName": "sample_150kB.pdf"
}
}
}
Keyboards
The API allows sending a custom keyboard, to supply the user with a set of predefined replies or actions. The keyboard can be attached to any message type or sent on it’s on. Once received, the keyboard will appear to the user instead of the device’s native keyboard. The keyboards are fully customizable and can be created and designed specifically for the account’s needs. The client will always display the last keyboard that was sent to it.
Read the following article to learn more about keyboards.
Keyboards can be attached to any message type and be sent and displayed together. To attach a keyboard to a message simply add the keyboard’s parameters to the message JSON.
Webhooks
Once you have your token you will be able to set your account’s webhook. This webhook will be used for receiving callbacks and user messages from Viber.
Setting the webhook will be done by calling the set_webhook API with a valid & certified URL. This action defines the account’s webhook and the type of events the account wants to be notified about.
For security reasons only URLs with valid and official SSL certificate from a trusted CA will be allowed. The certificate CA should be on the Sun Java trusted root certificates list.
Once a set_webhook request is sent Viber will send a callback to the webhook to check its availability and return a response to the user. The check succeeds if the Viber server receives HTTP status 200 in response to the callback, but fails if it receives any other status. If your set_webhook response doesn’t have “status”:0, please verify that all requests to your webhook URL receive HTTP status 200 in response.
Note that once you set your webhook the 1-on-1 conversation with your account will become available. To disable 1-on-1 conversation with your account you’ll need to remove your webhook – see removing your webhook below.
API allows you to receive user names and photos. This has been updated to comply with privacy laws and allow developers who don’t make use of user names and photos as part of their service to opt out. If you don’t use user names photos, please opt-out to default values.
To set the request, pass send_name and send_photo flags with the set_webhook request.
Note: This feature will work if the user has allowed “Content Personalisation” (More → Privacy → personal data). If the user has disallowed content personalization, you will receive placeholder values.
Setting a Webhook
Resource URL:
https://chatapi.viber.com/pa/set_webhook
{
"url":"https://webhook.site/35f7b639-04ab-4ee9-a17b-cacb929b0d5d?ta=0fc524f8-2a78-11ec-9424-482ae3643973",
"event_types":[
"delivered",
"seen",
"failed",
"subscribed",
"unsubscribed",
"conversation_started"
],
"send_name": true,
"send_photo": false
}
| Name | Description |
| ta= (query) | The TrafficAccountId associated with bot |
| url | required. Account webhook URL to receive callbacks & messages from users |
| event_types | optional. Indicates the types of Viber events that the account owner would like to be notified about.Don’t include this parameter in your request to get all events
Possible values: · delivered · seen · failed · subscribed · unsubscribed · conversation_started |
| send_name | optional. Indicates whether or not the bot should receive the user name. Default false |
| send_photo | optional. Indicates whether or not the bot should receive the user photo. Default false |
Set webhook Response
{
"status":0,
"status_message":"ok",
"event_types":[
"delivered",
"seen",
"failed",
"subscribed",
"unsubscribed",
"conversation_started"
]
}
Removing your webhook
Once you set a webhook to your bot your 1-on-1 conversation button will appear and users will be able to access it.
At the moment there is no option to disable the 1-on-1 conversation from the bot settings, so to disable this option you’ll need to remove the webhook you set for the account. Removing the webhook is done by Posting a set_webhook request with an empty webhook string.
Resource URL
https://chatapi.viber.com/pa/set_webhook
Post data
{
"url":""
}
Viber Pricing
Sessions are a conversation flow that allows you to communicate with a user in a defined time
frame.
To be used for customer support purposes, sessions will open up a new channel
of communication between customers and their subscribers.
The session rate will be applied ONLY if the end-user initiates the conversation. If you send a
message and it turns into a session (due to the development of a conversation) the session will
start from the first reply by you to the user.
Session Billing: You will be billed per session and not per each delivered message. This will
allow your team to send and receive multiple messages at a fixed per-session price.
Each session will be configured as follows:
● The session is set to a default period of 24 hours.
● Up to 60 messages can be sent in a single session by the business account. After 60 messages have been sent, a new session will begin automatically.
● A fixed rate is set according to the message type.
● You can send up to 5 messages in a row without the user’s reply, otherwise, the session
will end.
NOTE: Only session-based message types will be billed with the session rate once a session is in
progress. All other message types can still be used within a session but will be billed at a
regular rate.
! Important:
Transactional & Promotional messages
Customers will be able to send messages as:
• transactional (may contain text and optional URL related to the text: appointment reminders, transaction notifications, flight alerts etc.)
• promotional
The pricing depends on the country the message is sent to, as well as chosen message types. The Session messages are handled automatically by the Mitto platform and are.
Send Viber message
REQUEST: POST /message/send
{
"trafficAccountId": "fea74b75-8b26-4cef-8d79-162ceaefxxxx",
"destination": "01234567890",
"viber": {
"type": "regular",
"text":"Hi, how can I help you today?",
"mediaUrl":""
} }
RESPONSE
{
"messageId": "aaffcfbe-b3a4-4693-a7ae-06de09e3164a",
"sender": {
"id": "fb37041d-3d68-4882-82da-439635857de9",
"phoneNumber": "+38098222xxxx",
"name": "Mitto Viber"
},
"conversation": {
"id": "97972e94-ed7c-4258-b80e-54776833065d",
"participants": [
{
"id": "fb37041d-3d68-4882-82da-439635857de9",
"phoneNumber": "+38098222xxxx",
"name": "Mitto Viber"
}, {
"phoneNumber": "38591552xxxx"
}
] },
"createdAt": "2021-01-14T08:59:37.1742238Z",
"updatedAt": "2021-01-14T08:59:37.1742296Z",
"id": "091e918e-e551-4ed8-94d5-b37fac5bbf33",
"trafficAccountId": "fea74b75-8b26-4cef-8d79-162ceaefxxxx",
"deliveryStatus": "Ready"
}
Send Direct Viber message
Viber’s Business Messages API allows you to send verified transactional and promotional messages to users from your business account. Using a unique token for each message, you can track its movement from the moment your team hits ‘send’, until the end-user sees it.
Time To Live (TTL)
Each business message can be sent with a predefined Time To Live (TTL) value. This value will determine the maximum amount of time delivery attempts will be made for. The TTL value is set per message and usually depends on the content of the message. For example, it’s better to send more sensitive content with a shorter TTL (such as bank transaction details).The TTL can be set between 30 seconds (minimum)** and up to 1,209,600 seconds (maximum).We recommend not setting a low TTL when sending a large number of messages. This will help prevent cases where users will receive the messages but the delivery status will not be sent back in time, making the message appear as expired. In case no TTL is set in the request, message delivery attempts will continue for up to 14 days. If the user is not able to receive the message during that time, it will automatically gain an expired status.
Each request has optional parameter “ttl” where customer can specify Time To Live value.
{
...
"viber": {
...
"ttl": 120,
... }
}
**Recommended minimum for TTL is 60 seconds
URL Schemes
URL schemes allow you to create a shortcut to a specific screen within the app. You can utilize this if you wish to direct a user to the following:
- Start a call- Opens the Viber keypad with the phone number that you entered in the request.
Viber to Viber calls are free, however, if the phone number in the request is nota Viber
number the user will need to pay for the call(using Viber Out).
viber://keypad?number=%2B - Open a 1on1 chat-Opens a 1on1 chat with the sender (the sender needs to have a 2way
account).
viber://chat?service= - Open Viber QR scanner–Opens a QR scanner through Viber. Tapping the button will open the camera to capture a QR code.
viber://more/qr
Webhook
There is also a logic implemented to not send duplicate event to customers when the system receiving message from Viber user. Here it is how it works:
- If the event type is Delivered or Expired and there was *no* previous Delivered or Expired event, the event is processed on usual way.
- If the event type is Delivered or Expired but there was previous Delivered or Expired event, the event is being ignored.
- If the event type is Seen and there was *no* previous Seen event, the event is processed on usual way.
- If the event type is Seen and there was previous Seen event, the event is being ignored
- If the event type is Seen but there was *no* previous Delivered event, the event is beingignored.
Telegram bot manual + Examples
Telegram bot manual
Bots are simply Telegram accounts operated by software – not people.
A typical link to a bot looks like this:
Opening such a link starts a chat with that bot if you have Telegram installed. These links are easy to identify because all bot usernames must end in bot.
Bots: An introduction
Bots are third-party applications that run inside Telegram. Users can interact with bots by sending them messages. You control your bots using HTTPS requests.
How do bots work?
At the core, Telegram Bots are special accounts that do not require an additional phone number to set up. Users can interact with bots by sending messages, opening a chat with them or by adding them to groups.
Messages, commands and requests sent by users are passed to the software running on Chat platform. Our intermediary server handles all encryption and communication with the Telegram API for you. You communicate with this server via a simple HTTPS-interface that offers a simplified version of the Telegram API.
How do I create a bot?
There’s a… bot for that. Just talk to BotFather and follow a few simple steps. Once you’ve created a bot and received your authorization token.
How are bots different from humans?
- Bots have no online status and no last seen timestamps; the interface shows the label ‘bot’ instead.
- Bots have limited cloud storage — older messages may be removed by the server shortly after they have been processed.
- Bots can’t initiate conversations with users. A user must either add them to a group or send them a message first. People can use t.me/ links or username search to find your bot.
- Bot usernames always end in ‘bot’ (e.g., @TriviaBot, @GitHub_bot).
- When added to a group, bots do not receive all messages by default (see Privacy mode).
- Bots never eat, sleep or complain (unless expressly programmed otherwise).
BotFather
BotFather is the one bot to rule them all. It will help you create new bots and change settings for
existing ones.
Creating a new bot
Use the /newbot command to create a new bot. The BotFather will ask you for a name and username, then generate an authorization token for your new bot.
The name of your bot is displayed in contact details and elsewhere.
The Username is a short name, to be used in mentions and t.me links. Usernames are 5-32 characters long and are case insensitive, but may only include Latin characters, numbers, and underscores. Your bot’s username must end in ‘bot’, e.g. ‘tetris_bot’ or ‘TetrisBot’.
The token is a string along the lines of 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw that is required to authorize the bot and send requests to the Bot API. Keep your token secure and store it safely, it can be used by anyone to control your bot.
Generating an authorization token
If your existing token is compromised or you lost it for some reason, use the /token command to generate a new one.
Botfather commands
The remaining commands are pretty self-explanatory:
- /mybots — returns a list of your bots with handy controls to edit their settings
Edit bots
- /setname – change your bot’s name.
- /setdescription — change the bot’s description, a short text of up to 512 characters, describing your bot. Users will see this text at the beginning of the conversation with the bot, titled ‘What can this bot do?’.
- /setabouttext — change the bot’s about info, an even shorter text of up to 120 characters. Users will see this text on the bot’s profile page. When they share your bot with someone, this text is sent together with the link.
- /setuserpic — change the bot’s profile pictures. It’s always nice to put a face to a name.
- /deletebot — delete your bot and free its username.
Please note, that it may take a few minutes for changes to take effect.
Status alerts
In order to help developers keep their bots in shape, Botfather will send status alerts if it sees something is wrong.
We will be checking the number of replies and the request/response conversion rate for popular bots (~300 requests per minute: but don’t write this down as the value may change in the future).
If we get abnormally low readings, you will receive a notification from Botfather.
Responding to alerts
By default, you will only get one alert per bot per hour. Each alert has the following buttons:
- Fixed. Use this if you found an issue with your bot and fixed it. If you press the fix button, we will resume sending alerts in the regular way so that you can see if your fix worked within 5-10 minutes instead of having to wait for an hour.
- Support. Use this to open a chat with @BotSupport if you don’t see any issues with your bot or if you think the problem is on our side.
- Mute for 8h/1w. Use this if you can’t fix your bot at the moment. This will disable all alerts for the bot in question for the specified period of time. We do not recommend using this option since your users may migrate to a more stable bot. You can unmute alerts in your bot’s settings via Botfather.
Monitored issues
We will currently notify you about the following issues:
1. Too few **private messages** are sent compared to previous weeks: **{value}**
Your bot is sending much fewer messages than it did in the previous weeks. This is useful for newsletter-style bots that send out messages without prompts from the users. The larger the value, the more significant the difference.
2. Too few replies to incoming **private messages**. Conversion rate: **{value}**
Your bot is not replying to all messages that are being sent to it (the request/response conversion rate for your bot was too low for at least two of the last three 5-minute periods). To provide a good user experience, please respond to all messages that are sent to your bot. Respond to message updates by calling send… methods (e.g. sendMessage).
3. Too few answers to **inline queries**. Conversion rate: **{value}**
Your bot is not replying to all inline queries that are being sent to it, calculated in the same way as above. Respond to inline_query updates by calling answerInlineQuery.
4. Too few answers to **callback queries**. Conversion rate: **{value}**
Too few answers to **callback game queries**. Conversion rate: **{value}**
Your bot is not replying to all callback queries that are being sent to it (with or without games), calculated in the same way as above. Respond to callback_query updates by calling answerCallbackQuery.
Please note that the status alerts feature is still being tested and will be improved in the future.
Webhooks
To set webhook use API
https://core.telegram.org/bots/api#setwebhook
Use this method to specify a url and receive incoming updates via an outgoing webhook. Whenever there is an update for the bot, we will send an HTTPS POST request to the specified url, containing a JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of attempts. Returns True on success.
If you’d like to make sure that the Webhook request comes from Telegram, we recommend using a secret path in the URL, e.g. https://www.example.com/. Since nobody else knows your bot’s token, you can be pretty sure it’s us.
GET https://api.telegram.org/{{botid}}/setWebhook?url={{webhook_url}}?ta={{traffic_account_id}}
| Parameter | Description |
| botid | Your bot id (e.g.: 1825352151:AAGxS7thz5SEDuy-0tWWsV1ffUlR_x_QNQ) |
| webhook_url | Your webhook_url (e.g.: https://webhook.site/fbfbf687-2722-4ae0-8ee0-187edfdb8cb4) |
| traffic_account_id | Your traffic account_id (e.g.: 59af552a-e2f2-11eb-b862-482ae3643973) |
To delete webhook use API
https://core.telegram.org/bots/api#deletewebhook
Use this method to remove webhook integration if you decide to switch back to getUpdates.
Returns True on success
GET https://api.telegram.org/{{botid}}/deleteWebhook
| Parameter | Description |
| botid | Your bot id (e.g.: 1825352151:AAGxS7thz5SEDuy-0tWWsV1ffUlR_x_QNQ) |
To get info about webhook use API
https://core.telegram.org/bots/api#getwebhookinfo
Use this method to get current webhook status. Requires no parameters. On success, returns a WebhookInfo object. If the bot is using getUpdates, will return an object with the url field empty.
GET https://api.telegram.org/{{botid}}/getWebhookInfo
| Parameter | Description |
| botid | Your bot id (e.g.: 1825352151:AAGxS7thz5SEDuy-0tWWsV1ffUlR_x_QNQ) |
Examples
Send Telegram message
NOTE: You have to have installed Telegram chat application (on Desktop or phone) to be able to work with this API
First step is to go to:
https://t.me/
This API allows you to connect Telegram Bots to our system. Telegram Bots are special accounts that do not require an additional phone number to set up. These accounts serve as an interface for code running somewhere on your server.
Intermediary server will handle all encryption and communication with the Telegram API for you. You communicate with this server via a simple HTTPS-interface that offers a simplified version of the Telegram API.
(Optional). caption, 0-1024 characters. For parsing modes see Parsing modes
{
...
"telegram": {
...
"...": {
"caption": "Lorem ipsum dolor sit amet"
}
...
}
}
Sending silent message (without sound notification on client-side)
{
...
"telegram": {
...
"silent": true,
...
}
}
Parsing modes
Mode for parsing entities in the message text. See formatting options for more details.
| Parameter | Description |
| Default | plain text |
| Markdown | formatted in Markdown |
| Html | formatted in HTML |
| MarkdownV2 | formatted in MarkdownV2 |
Set parse mode to Html example:
{
...
"telegram": {
...
"...": {
"parseMode": "Html"
}
...
}
}
Text (URL) Only
Use this method to send text messages. Text of the message to be sent, 1-4096 characters after entities parsing. Mode for parsing entities in the message text is always set to default. For available parsing modes see Parsing modes
REQUEST: POST /messages/send
{
"trafficAccountId": "59af552a-e2f2-11eb-b862-482ae3643973",
"destination": "1861312834",
"telegram": {
"silent": true,
"text": {
"parseMode": "Html",
"message": "Hi, how can I help you today?"
}
}
}
Send URL
To disables link previews for links in this message set “noPreview” to true.
{
"trafficAccountId": "59af552a-e2f2-11eb-b862-482ae3643973",
"destination": "1861312834",
"telegram": {
"text": {
"noPreview": true,
"message": "https://github.com/TelegramBots/Telegram.Bot"
} }
}
Photo (image) Only
Use this method to send photos. Photo to send. Pass an HTTP URL as a String for Telegram to get a photo from the Internet. The photo must be at most 10 MB in size. The photo’s width and height must not exceed 10000 in total. Width and height ratio must be at most 20.
REQUEST: POST /messages/send
{
"trafficAccountId": "59af552a-e2f2-11eb-b862-482ae3643973",
"destination": "1861312834",
"telegram": {
"photo": {
"url": "https://file-examples-
com.github.io/uploads/2017/10/file_example_JPG_100kB.jpg",
"caption": "Example media (photo)"
} }
}
Document Only
Use this method to send general files. Only .gif, .pdf and .zip file types are allowed
NOTE: When sending “document” or “video”, Telegram accepts “thumb” parameter, however it seems like that parameter is being ignored and it will not be used anywhere (at least we could not find the place where it is used).
REQUEST: POST /messages/send
{
"trafficAccountId": "59af552a-e2f2-11eb-b862-482ae3643973",
"destination": "1861312834",
"telegram": {
"document": {
"url":"https://file-examples-com.github.io/uploads/2017/10/file-sample_150kB.pdf",
"caption": "Sample pdf document"
} }
}
Video Only
Use this method to send video files, Telegram clients support .mp4 and partially .ogg videos
NOTE: When sending “document” or “video”, Telegram accepts “thumb” parameter, however it seems like that parameter is being ignored and it will not be used anywhere (at least we could not find the place where it is used).
REQUEST: POST /messages/send
{
"trafficAccountId": "59af552a-e2f2-11eb-b862-482ae3643973",
"destination": "1861312834",
"telegram": {
"video": {
"url": "https://file-examples-
com.github.io/uploads/2018/04/file_example_OGG_480_1_7mg.ogg",
"caption": "Example video"
}
} }
Voice (audio) Only
Use this method to send audio files, if you want Telegram clients to display the file as a playable voice message. For this to work, your audio must be in an .ogg file encoded with OPUS or in .mp3
REQUEST: POST /messages/send
{
"trafficAccountId": "59af552a-e2f2-11eb-b862-482ae3643973",
"destination": "1861312834",
"telegram": {
"voice": {
"url": "https://file-examples-
com.github.io/uploads/2017/11/file_example_MP3_700KB.mp3",
"caption": "Example voice file"
} }
}
Location Only
Use this method to send point on the map.
REQUEST: POST /messages/send
{
"trafficAccountId": "59af552a-e2f2-11eb-b862-482ae3643973",
"destination": "1861312834",
"telegram": {
"location": {
"latitude": 46.100231,
"longitude": 19.664058
}
} }
Response (for all API requests)
SUCCESS (200)
{
"messageId": "efedcdeb-3993-4651-8390-8e52483e77d2",
"sender": {
"id": "3337c938-8929-42d1-9221-f3adf666e679",
"messagingAppIdentifier": "telegram_agent",
"name": "Mitto Telegram"
},
"conversation": {
"id": "17ae0d31-31d8-41fa-9332-2b1bbfb6056c",
"participants": [
{
"id": "3337c938-8929-42d1-9221-f3adf666e679",
"messagingAppIdentifier": "telegram_agent",
"name": "Mitto Telegram"
}, {
"messagingAppIdentifier": "1861312834"
}
] },
"createdAt": "2021-07-15T11:50:57.8954354Z",
"updatedAt": "2021-07-15T11:50:57.8956709Z",
"trafficAccountId": "59af552a-e2f2-11eb-b862-482ae3643973",
"deliveryStatus": "Ready"
}
Webhook
Telegram only supports receiving messages through webhook, currently there are no notification about message delivery or when the user reads the message.
To set webhook use API
https://core.telegram.org/bots/api#setwebhook
Use this method to specify a url and receive incoming updates via an outgoing webhook. Whenever there is an update for the bot, we will send an HTTPS POST request to the specified url,
containing a JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of attempts. Returns True on success.
If you’d like to make sure that the Webhook request comes from Telegram, we recommend using a secret path in the URL, e.g. https://www.example.com/<token> . Since nobody else knows your bot’s token, you can be pretty sure it’s us.
GET
https://api.telegram.org/
{{botid}}/setWebhook?url={{webhook_url}}?ta={{traffic_account_id}}
| Parameter | Description |
| botid | Your bot id /must start with “bot”/ (e.g.: bot1825352151:AAGxS7thz5SEDuy-0tWWsV1ffUl-R_x_QNQ) |
| webhook_url | Your webhook_url (e.g.:https://webhook.site/fbfbf687-2722-4ae0-8ee0-187edfdb8cb4) |
| traffic_account_id | Your traffic account_id (e.g.: 59af552a-e2f2-11eb-b862-482ae3643973) |
To delete webhook use API
https://core.telegram.org/bots/api#deletewebhook
Use this method to remove webhook integration if you decide to switch back to getUpdates.
Returns True on success.
GET https://api.telegram.org/{{botid}}/deleteWebhook
| Parameter | Description |
| botid | Your bot id /must start with “bot”/ (e.g.: bot1825352151:AAGxS7thz5SEDuy-0tWWsV1ffUl-R_x_QNQ ) |
To get info about webhook use API
https://core.telegram.org/bots/api#getwebhookinfo
Use this method to get current webhook status. Requires no parameters. On success, returns a WebhookInfo object. If the bot is using getUpdates, will return an object with the url field empty.
GET https://api.telegram.org/{{botid}}/getWebhookInfo
| Parameter | Description |
| botid | Your bot id /must start with “bot”/ (e.g.: bot1825352151:AAGxS7thz5SEDuy-0tWWsV1ffUl-R_x_QNQ ) |
Failover scenario
Failover enables you to reach customers by utilizing multiple communication channels provided by Mitto.
REQUEST:
{
"destination": "{destination}",
"whatsapp": {
"type": "regular",
"regular": {
"text": "{message text}",
"type": "text"
}
}, "sms": {
"text": "{message text}",
"sender": "{SMS sender}"
},
"failover": {
"type": "Timeout",
"timeoutFailover": {
"timeoutInSeconds": 20,
"status": "Delivered",
"trafficAccounts": [
"679b453b-c876-49b0-b30e-c2b4c1c6xxxx",
"679b453b-c876-49b0-b30e-c2b4c1c6xxxx"
]
} }
}
Response with message Ids:
["78e29b5e-6ce5-44ba-9a2e-98be495bde96", "78e29b5e-6ce5-44ba-9a2e-98be495bde91"]
All messages that will not be triggered with the status “Created” will be deleted after 60 days, and
will not be included in statistics.
Arguments:
- destination(required) – user messaging app identifier
- whatsapp(optional) – WhatsApp message object. Required if TA is linked to WhatsApp channel is used in failover flow.
- sms(optional) – SMS message object. Required if TA is linked to SMS channel is used in failover flow.
- viber(optional) – Viber message object. Required if TA is linked to Viber channel is used in failover flow.
- failover(required) – defines message failover flow.
Failover arguments:
- type(required) – failover type
- timeoutFailver(optional) – timeout failover object. Required if Failveor type is “Timeout”
TimeoutFailover arguments:
- timeoutInSeconds(optional) – failover timeout. If the timeout isn’t provided default will be used
status(required) – message status for condition - trafficAccounts(required) – traffic accounts. If the message fails or timeout exceeded for the first
- traffic account, the next traffic account will be used to send the message
Bulk
https://messaging.mittoapi.com/api/v{version}/Messages/sendbulk
This endpoint lets you use a POST request to send bulk messages using any supported channel. Bulk feature is available from the version 1.1
Request:
{
"destinations": [
"380981111111",
"380982222222"
],
"trafficAccountId": "4ae53d46-66d8-4aff-9f13-621f53b9xxxx",
"sms": {
"text": "hello",
"sender": "44750732xxxx"
},
"whatsApp": {},
"viber": {},
"gbm": {},
"failover": {}
}
Response with message Ids:
{
"bulkId": "543588f4-64a4-4271-9e72-a61cd3a03506",
"messages": [
{
"destination": "380981111111",
"trafficAccountId": "4ae53d46-66d8-4aff-9f13-621f53b9xxxx",
"messageId": "c032c9d2-49ba-4bae-85a4-7f83b99d480c"
}, {
} ]
}
"destination": "380982222222",
"trafficAccountId": "4ae53d46-66d8-4aff-9f13-621f53b9xxxx",
"messageId": "2086160c-1d0e-410a-a4ce-32caf804d489"
Arguments:
- destinations(required) – messaging application identifiers (phone numbers or custom ids related to messaging application)
- trafficAccountId(optional) – traffic account id(required if the message is sent without failover flow)
- whatsapp(optional) – WhatsApp object (required if TrafficAccount has WhatsApp messaging application) (For more information see WhatsApp regular messages and WhatsApp template
messages) - sms(optional) – SMS object (required if TrafficAccount has SMS messaging application) (For
more information see Sms) - viber(optional) – Viber object (required if TrafficAccount has Viber messaging application)
- failover(optional) – defines message failover flow.(For more information see Failover flows)