Amio Developer Hub

Welcome to Amio! Let's build on top of most reliable and full feature set API for messaging.

Get Started
Suggest Edits

Introduction

 

The Amio API unifies multiple messaging platforms under one REST API. Our API has resource-oriented URLs which is easy to predict. We also leverage HTTP response codes to indicate different errors. JSON is returned by all API endpoints including error responses.

Suggest Edits

Authentication

 

Authenticate your requests using access token available in Amio settings. Your access token carry many privileges, so keep it secret! You can authenticate your requests using Authorization HTTP header or by sending access token in query parameters.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {{OAUTH_TOKEN}}" https://api.amio.io/v1/messages
curl -X POST -H "Content-Type: application/json" https://amio.io/api/v1/messages?access_token={{OAUTH_TOKEN}}

Get Access Token

  1. Login to app.amio.io.
  2. Navigate to API settings.
  3. Copy the access token.
 

All API requests must be made over HTTPS with base URL https://api.amio.io/v1/. Data is sent and received in JSON format. Where possible, Amio API leverages appropriate HTTP verbs for requests.

HTTP Verb
Description

GET          

Used for resource retrieval.

POST

Resource creation or any other non-idempotent operation.

PUT

Used for idempotent operation as collection replacement etc.

PATCH

Update resource. Use {"key": "value"} for property update or create and {"key": null} for delete.

DELETE

Deletes a resource.

Suggest Edits

Responses

 

HTTP status codes are used to communicate result of your request.

HTTP Status Code
Description

200 OK                               

The request was successful.

201 Created

The request was successful and resource was created.

204 No Content

The request was successful and resource was deleted.

400 Bad Request

When the request could not be understood.

401 Unauthorized

Unauthorized request, i.e. missing access token.

403 Forbidden

The request is forbidden due to security reasons.

404 Not Found

Requested resource cannot be found.

405 Method Not Allowed

Requested method was not allowed, some other HTTP method is required.

422 Unprocessable Entity

The request was understood but cannot be processed as some validation error might occur. This might also represent an invalid state of the application or other similar problems.

429 Too Many Requests

In case you exceed maximum number of requests within given period, you receive this error response for any consequent requests. See Rate Limiting for more details.

502 Bad Gateway

In case an underlying API responds with an error. For example this might occur when message is being send to Facebook Messenger and Facebook page is disconnected from Amio.

Location Header

All responses with status code 201 Created contain Location header with actual location of newly created resource, i.e. Location: https://api.amio.io/v1/channels/{channel_id}.

As the HTTP status code returns a basic information about an error, we provide additional data in response body for further error indication. All errors have following format:

{
  "timestamp": "{{iso_8601_timestamp}}",
  "status": {
    "code": "{{HTTP_STATUS_CODE}}",
    "message": "{{HTTP_STATUS_MESSAGE}}"
  },
  "errors": ["{{LIST_OF_DETAIL_ERRORS}}"]
}
{
  "timestamp": "2016-12-21T11:17:56.397Z",
  "status": {
    "code": "405",
    "message": "Method Not Allowed"
  },
  "errors": [
    {
      "message": "Method POST is not allowed for resource /users."
    }
  ]
}
{
  "timestamp": "2016-12-21T11:17:56.397Z",
  "status": {
    "code": "422",
    "message": "Unprocessable Entity"
  },
  "errors": [
    {
      "field": "recipient",
      "rejected_value": null,
      "message": "Property 'recipient' cannot be null."
    }
  ]
}
Suggest Edits

Pagination

 

A resource which returns a list doesn't return all results at once. Instead, the number of results is constrained and you can traverse the results. For that purpose, the list requests accept the parameters max and offset.

Request Parameter
Default Value
Description

max

10

Maximal number of returned resources. Maximal allowed value is 100.

offset

0

The offset from the first result to list from.

All list responses return a number of total results in HTTP response header.

HTTP Response Header
Description

x-total-count

Number of total results.

An example which returns the 21st to 30th resource:

curl-H "Content-Type: application/json" -H "Authorization: Bearer {{OAUTH_TOKEN}}" https://api.amio.io/v1/channels?max=10&offset=20
Suggest Edits

Rate Limiting

 

Amio API has different rate limits for each pricing plan. We limit number of requests you can do within a hour. And number of simultaneous connections you can have opened to Amio servers.

Pricing Plan
Number of Requests
Simultaneous Connections

Free

1000

3

Developer

2000

10

Enterprise

custom

custom

You can check the returned HTTP headers of any API request to see your current rate limit status for maximum number of requests:

curl -i https://api.amio.io/v1/channels/{{channel_id}}

HTTP/1.1 200 OK
Date: Mon, 01 Jul 2013 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1491820066
HTTP Response Header
Description

X-RateLimit-Limit

The maximum number of requests that you are permitted to make per hour.

X-RateLimit-Remaining

Remaining number of requests.

X-RateLimit-Reset

Remaining time before the rate limit resets, in UTC epoch seconds.

Once you go over the rate limit you will receive an error response:

{
  "timestamp": "2016-12-21T11:17:56.397Z",
  "status": {
    "code": "429",
    "message": "Too Many Requests"
  },
  "errors": [
    {
      "message": "You have exceeded maximum number of requests and have been temporarily blocked. See documentation for more details: https://docs.amio.io/reference#rate-limiting"
    }
  ]
}
 

Run in Postman

Messages resource is the main entry point for sending messages. You have to specify a channel and contact to deliver the message.

The structure of JSON body is the same for all the channels. However, not all message types are supported by all channels.

Following chapters highlight only API requests that are common for all platforms. See platform specific documentation for more details:

Suggest Edits

List Messages

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id/messages
curl --request GET \
  --url https://api.amio.io/v1/channels/{{channel_id}}/contacts/{{contact_id}}/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "payload": "{{CONTENT_TYPE}}",
      "type": "{{CONTENT_PAYLOAD}}"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

direction

string

Specifies if the message has been received or sent: received, sent.

sent

string

Iso 8601 Timestamp - time when the message was sent.

delivered

string

Iso 8601 Timestamp - time when the message was delivered. null means that it hasn't been delivered yet.

read

string

Iso 8601 Timestamp - time when the message was read. null means that it hasn't been read yet.

channel

object

Channel in which the message was sent or received.

contact

object

Message belongs to a contact.

content

object

Content of the message.

Suggest Edits

Send Message

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "{{CONTENT_TYPE}}",
    "payload": "{{CONTENT_PAYLOAD}}"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "{{MESSAGE_ID}}",
  "channel": {
    "id": "6456078759331238786",
    "type": "{{CHANNEL_TYPE}}"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "{{CONTENT_TYPE}}",
    "payload": "{{CONTENT_PAYLOAD}}"
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to. You can get channel id in administration.

contact
object
contact.id
string
required

Id of the contact you wish to send the message to. There are different ways how to a contact (they are typically specific to a channel type), see Platform Specific Requests for more details.

content
object
content.type
string
required

Different types of the content can be sent: text, file, audio, video and image, structure, etc. See Platform Specific Requests for more detail.

content.payload
string
required

Payload is specific to message type. Different message types are documented in Platform Specific Requests.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

 

Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
  	"any": "arbitrary data"
  }
}
Suggest Edits

Notifications

 

Run in Postman

Notifications resource is used for sending various events like messages read or typing to the contact. If you're looking for events received from the contact, see the Webhooks documentation.

Notifications are available only on some platforms. See platform specific documentation for more details:

Suggest Edits

Send Notification

 
posthttps://api.amio.io/v1/notifications
{
  "channel": {
    "id": "6456078759331238786",
  },
  "contact": {
    "id": "6456078781510718339",
  },
  "type": "{{NOTIFICATION_TYPE}}"
}
A binary file was returned

You couldn't be authenticated

{
  "channel": {
    "id": "6456078759331238786",
    "type": "{{CHANNEL_TYPE}}"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "type": "{{NOTIFICATION_TYPE}}"
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the notification to. You can get channel id in administration.

contact
object
contact.id
string
required

Id of the contact you wish to send the notification to. There are different ways how to a contact (they are typically specific to a channel type), see Platform Specific Requests for more details.

type
string
required

Type specifies the notification to be sent they are different in each platform, see Platform Specific Requests.

 

Response Body Params

 

Run in Postman

Channel represents a medium through which you can send and receive messages. There are different channel types (facebook_messenger, viber, etc.).

Suggest Edits

List Channels

 
gethttps://api.amio.io/v1/channels
curl --request GET \
  --url https://api.amio.io/v1/channels
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078759331238786",
    "type": "{{CHANNEL_TYPE}}",
    "name": "Some Name",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger, viber, mobile.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

Suggest Edits

Get Channel

 
gethttps://api.amio.io/v1/channels/channel_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "{{CHANNEL_TYPE}}",
  "name": "Some Name",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  }
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger, viber, mobile.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "{{CHANNEL_TYPE}}",
  "name": "Some Name",
  "webhook": {
  	"url": "https://my-project.com/webhooks"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "{{CHANNEL_TYPE}}",
  "name": "Some Name",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  }
}

Body Params

type
string
required

Channel type, facebook_messenger, viber, mobile.

name
string

Name of the channel. If not set, it will be automatically filled with an account name of underlying platform.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger, viber, mobile.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "Some Name",
  "webhook": {
  	"url": "https://my-project.com/webhooks"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "{{CHANNEL_TYPE}}",
  "name": "Some Name",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger, viber, mobile.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

Remove webhook

Set webhook attribute to null if you'd like to remove channel webhook.

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel to be deleted.

 
 

Run in Postman

Contact represents the end user on given channel. Contact is automatically created whenever you receive a message from the user for the first time. However, there are also different ways how you can create the contact (i.e. for Mobile platform the user is created when you send a message to the given phone number).

Contact Merging

Amio doesn't implement any type of contact merging for one user on different platforms.

See channel specific requests to see differences between contacts on each channel:

Suggest Edits

List Contacts

 
gethttps://api.amio.io/v1/channels/channel_id/contacts
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078781510718339",
    "name": "Dietrich Bonhoeffer"
  }
]

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

Suggest Edits

Get Contact

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "name": "Dietrich Bonhoeffer"
}

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

Suggest Edits

Delete Contact

 
deletehttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact to be deleted.

 

Deleting a contact will also delete its conversation, messages and linked files.

 

Run in Postman

Settings resource is used for setting up certain properties of a channel like get started button, menu, etc.

Settings are available only on some channels:

Suggest Edits

Get Settings

 
gethttps://api.amio.io/v1/channels/channel_id/settings
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/settings
A binary file was returned

You couldn't be authenticated

{
  {{PLATFORM_SPECIFIC_SETTINGS}}
}

Path Params

channel_id
string
required

Id of the channel.

 
Suggest Edits

Update Settings

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  {{PLATFORM_SPECIFIC_SETTINGS}}
}
A binary file was returned

You couldn't be authenticated

{
  {{PLATFORM_SPECIFIC_SETTINGS}}
}

Path Params

channel_id
string
required

Id of the channel.

 
 

Webhooks allow you to receive real-time updates when a specific event occurs, i.e. message is received from a contact. These events are HTTP POST requests being sent to an endpoint of your server. Similarly to Amio Messaging API, body of such request is in JSON format. All events which happen in a specific channel are delivered to a single webhook url (i.e. https://your-server.com/webhook) which you can set in administration.

When you receive a webhook event, you should always return HTTP response in 2xx class, i.e. 200 OK in shortest time possible (we close the connections which takes longer then 60 seconds). If the webhook request fails or exceeds the maximum time, Amio will try to re-deliver the webhook again later (see Webhook Re-Delivery).

Webhook Content

All webhooks have following body structure:

{
  "event": "{{EVENT_NAME}}",
  "timestamp" : "{{ISO_8601_TIMESTAMP}}",
  "data" : {
    "{{event type specific data}}"
  }
}
Parameter
Type
Description

event

string

Event type name. See Events for complete list of events emitted by Amio.

timestamp

string

Iso 8601 Timestamp - time when we sent you the webhook.

data

object

Event type specific data object.

Webhook Re-Delivery

If your webhook fails with response code 4xx or 5xx, Amio will try to re-deliver the webhook again. There are several re-delivery events after 1, 5, 20, 60, 180 and 480 minutes. If all retries fail, the webhook call is discarded.

Set Webhook URL

  1. Login to app.amio.io.
  2. Pick a channel from channels.
  3. Select tab Webhook and set Webhook Url.

Different events are fired by Amio. There are common events to all channel types, however, there are also events specific to each channel, see Channel Events chapter for a complete list of channel-specific events.

Suggest Edits

Message Received

 

This event is fired when a contact sends a message to your channel. Request body contains channel type on which the event was handled as well as id of the contact. Different type of messages can be received based on channel.type.

{
  "event": "message_received",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "{{MESSAGE_ID}}",
    "channel": {
      "id": "{{CHANNEL_ID}}",
      "type": "{{CHANNEL_TYPE}}",
      "name": "{{CHANNEL_NAME}}"
    },
    "contact": {
      "id": "{{CONTACT_ID}}"
    },
    "content": {
      "payload": "What's the weather today?",
      "type": "text"
    },
    "nlp": {
      "intents": [
        {
          "confidence": 0.99847021852548,
          "id": "weather"
        }
      ],
      "native_data": {...}
    },
  }
}
Parameter
Type
Description

data

object

Object representing message received. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body except for the nlp key (see below). This key will be present only for received text messages on channels with NLP integration connected.

Natural Language Processing (NLP)

If there's an NLP integration connected to your channel, then your Message Received webhook will contain an nlp key with the result provided by the NLP service. Since different NLP services provide different extra capabilities and parameters beyond simple intent/entity extraction, we also include full JSON response from the service.

Parameter
Type
Description

nlp.intents

array of objects

List of intents ordered by confidence score.

nlp.intents[].id

string

Name (or other unique identifier) of the intent.

nlp.intents[].confidence

number

Confidence score of the intent.

nlp.native_data

object

Full unmodified JSON response as returned by the NLP service. For more information, please refer to the documentation of the service:
Wit.ai
Watson

Suggest Edits

Messages Delivered

 

This event notifies you of messages that were delivered to your contact.

{
  "event": "messages_delivered",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "messages": [
      { "id": "6456078996108088196" },
      { "id": "6456079002382766981" }
    ],
    "delivered_timestamp": "2016-10-06T13:40:01Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the messages were delivered.

data.messages

array of messages

Array of messages that were delivered. Every message will contain message.id. Depending on platform used, the message can contain other fields.

data.delivered_timestamp

string

Iso 8601 Timestamp. The time of message delivery to the user's device. This value may vary from webhook timestamp attribute if provided by the platform. If the platform doesn't provide this time, Amio uses time when the webhook came to our servers.

Suggest Edits

Message Failed

 

This event occurs only for some platforms and notifies you about a message that could not be. This may happen when given phone number is wrong or message expires, etc.

Only for Some Platforms

This webhook is used only by some platforms, i.e. by Viber, Mobile, etc.

{
  "event": "message_failed",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309",
    },
    "message": {
      "id": "6456078996108088196"
    },
    "error": {
      "code": 1,
      "message": "Error while processing the request."
    }
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the message was sent but not delivered.

data.message

object

Messages which was sent, will contain only message.id.

data.error.code

number

Error code, see errors below.

data.error.message

string

Detail message of an error, see errors below.

Errors

Error Code
Reason

1

Error while processing the request.

2

Sending messages to this user is blocked.

3

Cannot find user for given phone number.

4

Message failed to be delivered within 24 hours.

Suggest Edits

Messages Read

 

This event notifies you of messages that a contact has read.

{
  "event": "messages_read",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "last_read_timestamp": "2016-10-06T13:40:13Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact that has read messages delivered.

last_read_timestamp

string

Iso 8601 Timestamp

All messages before this timestamp were read.

Suggest Edits

Message Echo

 

Message echo event is invoked whenever a message is sent to a contact. This callback allows you to track all messages being sent no matter if they're sent by your channel or by someone else. For example, messages sent to Facebook users directly from Facebook Page administration or messages sent by some other Amio channel can be easily recorded.

{
  "event": "message_echo",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "{{MESSAGE_ID}}",
    "channel": {
      "id": "{{CHANNEL_ID}}",
      "type": "{{CHANNEL_TYPE}}",
      "name": "{{CHANNEL_NAME}}"
    },
    "contact": {
      "id": "{{CONTACT_ID}}"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our beloved customers!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
Parameter
Type
Description

data

object

Object representing message which is echoed. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body.

 

Once your server is configured to receive webhook events, it'll listen for any payload sent to the endpoint you configured. For security reasons, you probably want to limit requests to those coming from Amio. There are few ways to go about this, for example, you could opt to whitelist requests from Amio's IP address but a far easier method is to set up a secret token and validate the information using secret token.

You can find your secret token in Amio settings.

Amio uses this secret token to create a hash signature with each payload. The HTTP request will contain an X-Hub-Signature header which contains the SHA1 signature of the request payload, using the secret token as the key and prefixed with sha1= string. Your callback endpoint can verify this signature to validate the integrity and origin of the payload.

Here is the code how to calculate X-Hub-Signature:

const crypto = require('crypto')

function calculateXHubSignature(secret, body /* as string */) {
  const hmac = crypto.createHmac('sha1', secret)
  hmac.update(body)
  return `sha1=${hmac.digest('hex')}`
}
import org.apache.commons.codec.binary.Hex

import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.nio.charset.Charset

class WebhookSecurityService {
  
  public static String calculateXHubSignature(String secret, String body) {
    Mac hmac = Mac.getInstance("HmacSHA1");
    hmac.init(new SecretKeySpec(secret.getBytes(Charset.forName("UTF-8")), "HmacSHA1"));
    return "sha1=" + Hex.encodeHexString(hmac.doFinal(body.getBytes(Charset.forName("UTF-8"))));
  }
}
// credits goes to Michal Pustějovský <mpustejovsky@dpd.cz>

using System;
using System.Text;
using System.Security.Cryptography;

namespace Webhook
{
    public class WebhookSecurityService
    {
        public string WebhookSecurity(string secret, string body)
        {
            var hmac = new HMACSHA1(Encoding.UTF8.GetBytes(secret));
            var byteHash = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
            return "sha1=" + BitConverter.ToString(byteHash).Replace("-", "").ToLower();
        }
    }
}

Verify your algorithm with following values:

secret = 'WebhookSecret'
body = '{"event":"messages_delivered","timestamp":"2018-03-01T11:54:14.886Z","data":{"channel":{"id":"viber_service_messages_test","type":"viber"},"contact":{"phone_number":"+420606123456"},"messages":[{"id":"151990525359991"}]}}'

The calculated X-Hub-Signature should equal to sha1=cb041d03489e961730cb6c7a6d1edf58ae88ef13.

Suggest Edits

Facebook Messenger

 

See Amio Documentation for getting started manuals and complete description of Facebook Messenger platform.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify a Facebook contact with one of the following attributes:

Contact Id

{
  "contact": {  
    "id": "6456078781510718339"
  },
  "channel": {...},
  "content": {...}
}

You receive contact.id when the user starts a conversation with you, see Entry Points for more details.

Phone Number

You can send a message using a phone number you already have (see Phone Number Entry Point for more details). Attributes first_name and last_name are optional and just help to match the phone number with an existing Facebook User.

{
  "contact": {
    "phone_number": "+1 (555) 857-6309",
    "first_name": "Anthony",
    "last_name": "Hopkins"
  },
  "channel": {...},
  "content": {...}
}
{
  "id": "...",
  "contact": {
    "id": "15234390803083474",
    "phone_number": "15558576309"
  },
  "channel": {...},
  "content": {...}
}

Opt-in and Messages Delivered Webhooks

When you send a message using phone number, you can listen to Opt-in Webhook which is fired when the user confirms your request. You should however also listen to Messages Delivered Webhook which is fired for any further message sent after the user opts in.

Phone Number Format

Note that the phone number in response is in E.164 format. All responses and webhooks coming from Amio use this format.

Message Tags

Facebook requires you to comply with subscription messages policy when sending messages using phone number. This applies for all messages sent before the user opts in to receive messages from you.

Therefore, when you send messages before the opt-in, Amio automatically sets tag non_promotional_subscription (see tags) to your messages. You can set appropriate message tag which will be used after the user opts in (i.e. shipping_update).

User Ref

Opt-in Webhook delivers a user_ref attribute which can be used for sending the first message to the user.

{
  "contact": {
    "user_ref": "{{YOUR_CUSTOM_USER_REF}}"
  },
  "channel": {...},
  "content": {...}
}
{
  "id": "...",
  "contact": {
    "id": "15234390803083474",
    "user_ref": "{{YOUR_CUSTOM_USER_REF}}"
  },
  "channel": {...},
  "content": {...}
}
Suggest Edits

List Messages

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id/messages
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

direction

string

Specifies if the message has been received or sent: received, sent.

sent

string

Iso 8601 Timestamp - time when the message was sent.

delivered

string

Iso 8601 Timestamp - time when the message was delivered. null means that it hasn't been delivered yet.

read

string

Iso 8601 Timestamp - time when the message was read. null means that it hasn't been read yet.

channel

object

Channel in which the message was sent or received.

contact

object

Message belongs to a contact.

content

object

Content of the message

posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to text.

content.payload
string
required

Text to be sent. Maximum size of 640 characters.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to image.

content.payload
object
content.payload.url
string
required

Url of the image to be sent.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "audio",
    "payload": {
      "url": "http://dubioza.org/site/wp-content/uploads/2016/02/1.-All-Equal-feat-BEE2.mp3"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "audio",
    "payload": {
      "url": "http://dubioza.org/site/wp-content/uploads/2016/02/1.-All-Equal-feat-BEE2.mp3"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to audio.

content.payload
object
content.payload.url
string
required

Url of the audio to be sent.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "video",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339",
  },
  "content": {
    "type": "video",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to video.

content.payload
object
content.payload.url
string
required

Url of the video to be sent.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "file",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "file",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to file.

content.payload
object
content.payload.url
string
required

Url of the file to be sent.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
 

Location Messages are only Received

On Facebook Messenger, location messages cannot be sent however they can be received from the user, see Receive Message webhooks.

{
  "channel": { ... },
  "contact": { ... },
  "content": {
    "type": "location",
    "payload": {
      "latitude": 50.0902163,
      "longitude": 14.3973905
    }
  }
}
Parameter
Type
Description

content.type

string

Message type location.

content.payload.latitude

double

Location sent by user - latitude.

content.payload.longitude

double

Location sent by user -
longitude.

Suggest Edits

Receipt

Receipt type of message is suitable for sending order confirmation with all items listed, address and payment summary.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "receipt",
    "payload": {
      "order_id": "id546584", 
      "timestamp": "2016-10-06T13:42:48Z",
      "currency": "USD",
      "payment_method": "Visa ***8138.",
      "url_order": "http://petersapparel.parseapp.com/order?order_id=id546584",
      "shipping_address": {
        "name": "Tomáš Baťa",
        "address_line_1": "tř. Tomáše Bati 46",
        "address_line_2": "company Bata a.s.",
        "city": "Otrokovice",
        "postal_code": "765 02",
        "state": "Zlín Region",
        "country_code": "CZ"
      },
      "items": [ 
        {
          "title":"Winter Mens' Footware",
          "text":"100% Leather",
          "quantity":1,
          "price":67.5,
          "image_url":"http://3-cz-cdn.bata.eu/gallery/1/6/4/5/7/c.jpg"
        }
      ],
      "summary": {
        "shipping": 4.95,
        "tax": 6.19,
        "total": 78.64
      }
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "receipt",
    "payload": {
      "order_id": "id546584", 
      "timestamp": "2016-10-06T13:42:48Z",
      "currency": "USD",
      "payment_method": "Visa ***8138.",
      "url_order": "http://petersapparel.parseapp.com/order?order_id=id546584",
      "shipping_address": {
        "name": "Tomáš Baťa",
        "address_line_1": "tř. Tomáče Bati 46",
        "address_line_2": "company Bata a.s.",
        "city": "Otrokovice",
        "postal_code": "765 02",
        "country_code": "CZ"
      },
      "items": [ 
        {
          "title":"Winter Mens' Footware",
          "text":"100% Leather",
          "quantity":1,
          "price":67.5,
          "image_url":"http://3-cz-cdn.bata.eu/gallery/1/6/4/5/7/c.jpg"
        }
      ],
      "summary": {
        "shipping": 4.95,
        "tax": 6.19,
        "total": 78.64
      }
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to receipt.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

payload
object
payload.order_id
string
required

Order id. Has to be unique for each recepient.

payload.timestamp
date

Timestamp of the order. Must be in ISO 8601 timestamp form, e.g. 2016-10-06T13:42:48Z. This timestamp is zone agnostic it means that if you use zone in your format, the time will be shifted to UTC.

payload.currency
string
required

Currency in the form of ISO 4217, e.g. USD or CZK.

payload.url_order
string

URL with order details.

payload.payment_method
string
required

Payment method. This can be a custom string, e.g. Visa 1234.

shipping_address
object
shipping_address.name
string
required

Recipient's full name. Required if address is set.

shipping_address.address_line_1
string

Address line 1, P.O. box, company name, c/o. Required if city is set.

shipping_address.address_line_2
string

Apartment, suite, unit, building, floor, etc.

shipping_address.city
string

City. Required if address is set. Required if address_line_1is set.

shipping_address.postal_code
string

Postal Code. Required if address is set. Required if address_line_1is set.

shipping_address.state
string

State abbreviation or Region/Province (international). Required if address_line_1is set.

shipping_address.country_code
string

Country code according to ISO 3166 - alpha2. Required if address_line_1is set.

items
object
items.title
string

Item title. Required if item is set.

items.text
string

Item subtitle.

items.quantity
int32

Quantity of items.

items.price
double

Price of the item. 0 is allowed. Required if item is set.

items.image_url
string

Url of the item image.

summary
object
summary.shipping
double

Cost of shipping.

summary.tax
double

Total tax.

summary.total
double
required

Total cost.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
Facebook Messenger receipt.

Facebook Messenger receipt.

Receipt detail is shown when user taps on the receipt.

Receipt detail is shown when user taps on the receipt.

Suggest Edits

Structure

Structure messages allows you to send well formatted message containing image, title, description, link and action buttons. This format is suitable when you'd like to send messages with visual content and possible call to action buttons, i.e. today's menu of your restaurant.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad with smoked eggplant and zuchhini and dried tomatoes",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad with smoked eggplant and zuchhini and dried tomatoes",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string

Title of the message. Max size 80 characters. Title has to be specified with one more additional attribute: text, image_url or buttons. You can also omit the title attribute and use only text and buttons attributes.

payload.text
string

Message text. Max size 80 characters. However, you can use up to 640 characters if you use text with buttons only.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Limetted to 3 buttons. See Buttons chapter for more details.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 

Different Structure Messages

Structure message can be composed from subset of attributes: title can be combined with one or more attributes (i.e. Title & Text, Title, Text & Image, etc.), text can be combined only with title or button (Title & Text and Text & Button).

Suggest Edits

Structure - Horizontal Scroll

It is also possible to send multiple structured messages. They are displayed as a horizontal scroll within the Facebook Messenger.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "structure",
    "payload": [
      {
        "title": "Leaf salad with smoked eggplant and zuchhini and dried tomatoes",
        "text": "9.5 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-1"
          }
        ]
      },
      {
        "title": "Beef burger with Coleslaw salad",
        "text": "12.0 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/9/9b/YOKOSUKA-NAVY-BURGER-TSUNAMI.JPG",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-2"
          }
        ]
      }
    ]
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "structure",
    "payload": [
      {
        "title": "Leaf salad with smoked eggplant and zuchhini and dried tomatoes",
        "text": "9.5 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-1"
          }
        ]
      },
      {
        "title": "Beef burger with Coleslaw salad",
        "text": "12.0 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/9/9b/YOKOSUKA-NAVY-BURGER-TSUNAMI.JPG",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-2"
          }
        ]
      }
    ]
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string
required

Title of the message. Max size 80 characters. Title has to be specified with one more additional attribute: text, image_url or buttons.

payload.text
string

Message text. Max size 80 characters.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Limetted to 3 buttons. See Buttons chapter for more details.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
 

Buttons can be used in Structure messages. They provide the user with ability to perform a predefined action, such as opening Messenger webview, send a postback message, share a content, and more.

Url Button

The Url Button opens an in-app Messenger webview (browser) with given address.

...
buttons: [
  {
    "type": "url",
    "title": "Freedom",
    "payload": "https://en.wikipedia.org/wiki/Liberty"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to url.

title*

string

Title of the button. Max size is 20 characters.

payload*

string

Url to be opened.

Requires Domain Whitelisting

Url passed to the webview with url button must be whitelisted (including subdomains). See domain whitelisting.

Postback Button

When the user taps on the postback button, it sends developer-defined payload back on Postback Received webhook. You can perform an action or reply back when this happens.

...
buttons: [
  {
    "type": "postback",
    "title": "List Items",
    "payload": "{{PASS_THROUGH_PARAM}}"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to postback.

title*

string

Title of the button. Max size is 20 characters.

payload*

string

Any arbitrary data you can send to Postback Received webhook. Max size is 1000 characters.

Call Button

Call Button initiates a phone call.

...
buttons: [
  {
    "type": "phone",
    "title": "Call Us",
    "payload": "+1 (555) 857-6309"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to phone.

title*

string

Title of the button. Max size is 20 characters.

payload*

string

Phone number that will be dialed. Make sure the phone number is in international format.

Suggest Edits

Quick Replies

 

Quick Replies are buttons with a set of pre-defined short replies that appear above the user input, making the keyboard less important. When a button is tapped, the message is sent as a text and you'll receive it to your webhook. The buttons are dismissed as soon as user taps one or reply with own text.

Quick Replies can be attached to any Message type in the content.quick_replies attribute.

{
  "channel": { ... },
  "contact": { ... },
  "content": {
    "type": "...",
    "payload": "...",
    "quick_replies": [
      { "..." },
      { "..." },
      { "..." }
    ]
  }
}
Parameter
Type
Description

quick_replies

array of objects

Holds a list of maximally 11 objects of Text Quick Reply, User Location Quick Reply, Email Quick Reply or Phone Number Quick Reply type.

Text Quick Reply

Text Quick Replies show buttons with text and optionally a small image icon. Each button can also hold a developer-defined payload, which is invisible to the user but can be used for automated processing. When the user taps on the button, it fires Message Received webhook with text and developer payload if specified.

...
"quick_replies": [
  {
    "type": "text",
    "title": "Pilsner Urquell",
    "payload": "DEVELOPER_DEFINED_PAYLOAD",
    "image_url": "http://www.logotypes101.com/logos/778/70D1EF7E13BFAC232F2D05DE2E5594E0/pubisc.png"
  },
  {
    "type": "text",
    "title": "Heineken",
    "payload": "DEVELOPER_DEFINED_PAYLOAD",
    "image_url": "http://www.logotypes101.com/free_vector_logo_png/33082/85D3F063102F2476DC36D26D4D7A15C1/Heineken29"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to text.

title*

string

Button title with limit of 20 character; longer text gets truncated.

payload*

string

Developer-defined payload with limit of 1000 character. This payload is delivered back together with title as a text message in Message Received webhook.

image_url

string

Image to be displayed on the button. It should have dimension of at least 24x24 px.

UX - `payload` might not be delivered

Be aware that the user might send the reply by typing it into user input. In this case you don't receive the payload metadata. However, you should handle this message same as the user taps on the quick reply button.

User Location Quick Reply

Users can be prompt for their location via quick replies. It shows a Send Location button. When the user taps on the button, it fires Message Received webhook with location coordinates.

...
"quick_replies": [
  {
    "type": "location"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to location.

Email Quick Reply

Email can also be requested using a quick reply. If the user has an email set in the profile, then it will be pre-filed as a quick reply button. When the user taps on the button, it fires Message Received webhook with text containing his email address.

...
"quick_replies": [
  {
    "type": "email"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to email.

Phone Number Quick Reply

Phone number quick reply allows you to easily ask for users' phone number. If the user has a phone number set in the profile, then it will be pre-filed as a quick reply button. When the user taps on the button, it fires Message Received webhook with text containing his phone number.

...
"quick_replies": [
  {
    "type": "phone_number"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to phone_number.

 

Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
    "any": "arbitrary data"
  }
}

Reserved metadata keywords

platform_metadata - Metadata to be sent directly to Facebook Messenger API, see Platform Metadata below.
tag - Facebook Messenger allows to send messages with tags, see Message Tags documentation.

Platform Metadata

Facebook Messenger API has its own concept of metadata. You can send metadata as a string with any message, see Facebook Messenger API documentation. Amio API reserves platform_metadata keyword to be mapped to original Facebook Messenger metadata attribute.

You can use platform_metadata attribute to send metadata directly to Facebook Messenger API. This can be received by other programs listening on the same Messenger account but not using Amio API.

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
    "platform_metadata": "these data are going to be sent directly to Facebook Messenger API as metadata attribute"
  }
}
Parameter
Type
Description

platform_metadata

string

Platform specific metadata to be sent directly to Facebook Messenger API as a metadata attribute, see Facebook Messenger API documentation. Max size 1000 characters.

Facebook Messenger types are used to explicitly specify the purpose of a message and ensure that given message complies with Facebook policies. Amio uses default message type so you don't have to care about setting this attribute. However, you can specify a message type for advanced scenarios.

To send a message type, you can use type reserved keyword in metadata attribute:

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
    "type": "response"
  }
}
Parameter
Type
Description

type

string

Message type: response, update. Type can be set only if Tags are not used.


response (default): Message is in response to a received message. This includes promotional and non-promotional messages sent inside the 24-hour standard messaging window or under the 24+1 policy. For example, use this tag to respond if a person asks for a reservation confirmation or an status update.


update: Message is being sent proactively and is not in response to a received message. This includes promotional and non-promotional messages sent inside the the 24-hour standard messaging window or under the 24+1 policy.

The basic Facebook App permission pages_messaging allows you to send messages within the 24 hours window after last message received from user plus 1 message outside this time frame, see Facebook App Permissions. Message tags give you the ability to send messages to the user outside of this timeframe. However, they should strictly comply with Facebook Messenger Platform Policy.

To send a message tag, you can use tag reserved keyword in metadata attribute:

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
    "tag": "shipping_update"
  }
}
Parameter
Type
Description

tag

string

Tag to be sent with message: account_update, application_update, appointment_update, community_alert, confirmed_event_reminder, feature_functionality_update, game_event, issue_resolution,
non_promotional_subscription, pairing_update, payment_update, personal_finance_update, reservation_update, shipping_update, ticket_update, transportation_update, see Facebook Documentation for full description. Tag can be set only if Types are not used.

Suggest a New Message Tag

You can contact us at support@amio.io. and we will ask Facebook to add new message tag.

Suggest Edits

Notifications

 

Run in Postman

Notifications resource is used for sending various events like messages read or typing to the contact. If you're looking for events received from the contact, see the Webhooks documentation.

Suggest Edits

Send Notification

 
posthttps://api.amio.io/v1/notifications
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "type": "typing_on"
}
A binary file was returned

You couldn't be authenticated

{
  "channel": {
    "id": "6456078759331238786",
  },
  "contact": {
    "id": "6456078781510718339",
  },
  "type": "typing_on"
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the notification to. You can get channel id in administration.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

type
string
required

Type specifies the notification to be sent and can have following values:

messages_read - shows that all received messages from contact are read
typing_on - shows the typing indicator
typing_off - hides the typing indicator - if you don't switch off the typing indicator, it is switched off automatically (typically in 20 seconds).

 
Typing on notification sent.

Typing on notification sent.

 

Run in Postman

Channel represents a medium through which you can send and receive messages.

Suggest Edits

List Channels

 
gethttps://api.amio.io/v1/channels
curl --request GET \
  --url https://api.amio.io/v1/channels
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078759331238786",
    "type": "facebook_messenger",
    "name": "Amio",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    },
    "facebook_page": {
      "id": "747722755375845",
      "name": "Amio",
      "category": "Internet Company",
      "access_token": "9mqyDMPBtgRG3{nWLYYh"
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

facebook_page

object

Represents a facebook page connected to the channel. You can send and receive message only If facebook page is connected.

facebook_page.id

string

Id of the connected page.

facebook_page.name

string

Name of the facebook page.

facebook_page.category

string

Category of the facebook page.

facebook_page.access_token

string

Long lived facebook page access token with required permission.

Suggest Edits

Get Channel

 
gethttps://api.amio.io/v1/channels/channel_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "facebook_messenger",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "facebook_page": {
    "id": "747722755375845",
    "name": "Amio",
    "category": "Internet Company",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

facebook_page

object

Represents a facebook page connected to the channel. You can send and receive message only If facebook page is connected.

facebook_page.id

string

Id of the connected page.

facebook_page.name

string

Name of the facebook page.

facebook_page.category

string

Category of the facebook page.

facebook_page.access_token

string

Long lived facebook page access token with required permission.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "facebook_messenger",
  "name": "Amio Channel",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "facebook_page": {
    "id": "747722755375845",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "facebook_messenger",
  "name": "Amio Channel",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
    "ssl_verification": true
  },
  "facebook_page": {
    "id": "747722755375845",
    "name": "Amio",
    "category": "Internet Company",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}

Body Params

type
string
required

Channel type, facebook_messenger.

name
string

Name of the channel. If not set, it will be filled with connected Facebook Page name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

facebook_page
object
facebook_page.id
string
required

Id of the facebook page to be connected.

facebook_page.access_token
string
required

Access token to be used for Facebook API calls. This can be any type of access token with required permission. Typically, you will send User Access Token obtained after successful Facebook OAuth login procedure. When you create a channel, we request for long lived Page Access Token what ensures that the access token won't expire. See Facebook documentation for more details.

You can only use access tokens that were generated for a certain Facebook App. If you want to use your own Facebook App, let us know at support@amio.io.. This SO answer explains how to generate access_token for a given Facebook Application.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

facebook_page

object

Id of the connected page.

facebook_page.name

string

Name of the facebook page.

facebook_page.category

string

Category of the facebook page.

facebook_page.access_token

string

Long or short lived facebook page access token with required permission.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "Amio",
  "webhook": {
    "url": "https://my-project.com/webhooks",
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "facebook_messenger",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "facebook_page": {
    "id": "747722755375845",
    "name": "Amio",
    "category": "Internet Company",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel. Might be an arbitrary name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

facebook_page

object

Id of the connected page.

facebook_page.name

string

Name of the facebook page.

facebook_page.category

string

Category of the facebook page.

facebook_page.access_token

string

Long lived facebook page access token with required permission.

Remove webhook

Set webhook attribute to null if you'd like to remove channel webhook.

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel to be deleted.

 
 

Run in Postman

Contact represents the Facebook Messenger user. Contact is automatically created whenever you receive a message from the user for the first time. However, there are also different ways how the contact is created (i.e. when you send a message to the Facebook Messenger user using phone number you already have, see Facebook Messenger Entry Points).

Suggest Edits

List Contacts

 
gethttps://api.amio.io/v1/channels/channel_id/contacts
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078781510718339",
    "name": "Dietrich Bonhoeffer",
    "gender": "male",
    "locale": "de",
    "time_zone": "+02:00",
    "photo_url": "https://scontent.xx.fbcdn.net/v/t1.0-1/541992_511761562179706_48931455_n.jpg?oh=1b30d9f950c70b19cf99ef8ea81a169e&oe=5A5108B3"
  }
]

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

gender

string

User's gender either male or female.

locale

string

User’s locale.

time_zone

string

Time zone set by the user.

photo_url

string

Url to profile picture of the user.

Suggest Edits

Get Contact

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "phone_number": "15558576309",
  "user_ref": "123456789",
  "name": "Dietrich Bonhoeffer",
  "gender": "male",
  "locale": "de",
  "time_zone": "+02:00",
  "photo_url": "https://scontent.xx.fbcdn.net/v/t1.0-1/541992_511761562179706_48931455_n.jpg?oh=1b30d9f950c70b19cf99ef8ea81a169e&oe=5A5108B3"
  }

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

phone_number

string

Phone number of the contact (E.164 format). Only available if you have previously sent a message to this contact using a phone number. For more details see Using phone number.

user_ref

string

User_ref instead of id until you get a real id. For more details have a look at how Checkbox plugin works

name

string

Name of the contact.

gender

string

User's gender either male or female.

locale

string

User’s locale.

time_zone

string

Time zone set by the user.

photo_url

string

Url to profile picture of the user.

Suggest Edits

Delete Contact

 
deletehttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact to be deleted.

 
 

Run in Postman

Facebook Messenger allows you to set variety of items which enhance the feel and look of your Messenger channel for your users:

Suggest Edits

Get Settings

 
gethttps://api.amio.io/v1/channels/channel_id/settings
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/settings
A binary file was returned

You couldn't be authenticated

{
  "get_started_button": {...},
  "menu": {...},
  "user_input_enabled": ...,
  "domains_whitelist": [...]
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

get_started_button

object

Object specifying get started button properties, see Get Started Button.

menu

object

Menu for messenger thread, see Menu.

user_input_enabled

boolean

Enables or disables the user from sending a text message to you, see User Input enabled.

domains_whitelist

array

Some Facebook Messenger features needs to have used domains whitelisted, see Domains Whitelist.

Suggest Edits

Get Started Button

 

Get Started Button is visible on the welcome screen when the user comes for the first time. If the user tapes the button, it will trigger Postback Received webhook and deliver the user's page-scoped id.

You can then present a personalised message to greet the user or provide a structured message with buttons to prompt him or her to take an action. The button is a good mean to increase conversions. Adding a "Get Started" button resolves the issue of users not knowing what to write to break the ice with your bot.

Get started button on conversation start.

Get started button on conversation start.

Suggest Edits

Create/Update

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  }
}  
A binary file was returned

You couldn't be authenticated

{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  }
}  

Path Params

channel_id
string
required

Id of the channel.

Body Params

get_started_button
object
get_started_button.payload
string

Any arbitrary data you will receive in Postback Received webhook when user clicks the button.

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "get_started_button": null
}  
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

 

Creating a menu in Facebook Messenger, you can highlight important actions or provide link to a webpage. Menu for Facebook Messenger is hierarchical and consists of different menu item types:

  • Url
  • Postback
  • Nested Menu

Menu requires Get Started Button

You must set a Get Started Button if you want to use menu in Facebook Messenger.

Menu in Facebook Messenger.

Menu in Facebook Messenger.

Suggest Edits

Create/Update

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "menu": { 
    "payload": {
      "menu_items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com"
        },
        {
          "type": "postback",
          "title": "POSTBACK Item",
          "payload": "POSTBACK DATA"
        },
        {
          "type": "menu",
          "title": "NESTED Item",
          "payload": {
            "menu_items": [
              {
                "type": "url",
                "title": "NESTED URL Item",
                "payload": "http://www.google.com"
              },
              {
                "type": "postback",
                "title": "NESTED POSTBACK Item",
                "payload": "POSTBACK DATA"
              }
            ]
          }
        }
      ]
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "menu": { 
    "payload": {
      "menu_items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com"
        },
        {
          "type": "postback",
          "title": "POSTBACK Item",
          "payload": "POSTBACK DATA"
        },
        {
          "type": "menu",
          "title": "NESTED Item",
          "payload": {
            "menu_items": [
              {
                "type": "url",
                "title": "NESTED URL Item",
                "payload": "http://www.google.com"
              },
              {
                "type": "postback",
                "title": "NESTED POSTBACK Item",
                "payload": "POSTBACK DATA"
              }
            ]
          }
        }
      ]
    }
  }
}

Path Params

channel_id
string
required

Id of the channel.

Query Params

manu.payload.menu_items
array
required

Array of menu item objects, see below. Maximum allowed size is 3.

 

Response Body Params

Url Menu Item

Parameter
Type
Description

type

string

Must be set to url.

title

string

Title of the menu item. Maximum size of 30 characters.

payload

string

Must be a valid URL.

Postback Menu Item

Parameter
Type
Description

type

string

Must be set to postback.

title

string

Title of the menu item. Maximum size of 30 characters.

payload

string

This data will be sent back to Postback Received webhook. Maximum size of 1000 characters.

Nested Menu

Parameter
Type
Description

type

string

Must be set to menu. The maximal hierarchical depth is 3 levels.

title

string

Title of the menu item. Maximum size of 30 characters.

payload

object

Object with attribute menu_items holding an array of items (url, postback, menu). The maximum number of items is 5 objects.

Testing Tips

Facebook Messenger menu is cached by default (it is updated after a certain period of time). If you update the menu while testing, you can force this update to happen by deleting the messenger thread and then beginning the conversation once again.

Menu is visible only if:

  • Facebook Messenger has a version 106 and above.
  • The attached Facebook page must be published.
Nested menu items.

Nested menu items.

patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  menu: null
}
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

 
Suggest Edits

User Input Enabled

 

You can disable the user from writing you a message back using user_input_enabled settings. This force to the user to use only buttons provided in structured messages or in menu.

User Input Enabled requires Menu

You must set a Menu if you want to disable user input.

Disabled user input.

Disabled user input.

patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "user_input_enabled": false
}  
A binary file was returned

You couldn't be authenticated

{
  "user_input_enabled": false
}  

Path Params

channel_id
boolean
required

Id of the channel.

Body Params

user_input_enabled
string
required

Set to false in order to disable the users' input.

 
Suggest Edits

Domains Whitelist

 

Some features like Checkbox Plugin require domains to be whitelisted.

Whitelisting in Facebook Page Settings

In addition to domains whitelist API, you can whitelist domains in Facebook Page administration:

  1. Click Settings in your Facebook Page.
  2. Click Messenger Platform on the left menu.
  3. Edit domains in Whitelisted Domains sectionn.
Suggest Edits

Create/Update

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "domains_whitelist": [
     "https://amio.io"
  ]
}  
A binary file was returned

You couldn't be authenticated

{
  "domains_whitelist": [
     "https://amio.io"
  ]
}  

Path Params

channel_id
boolean
required

Id of the channel.

Body Params

whitelisted_domains
array of strings
required

A list of domains to whitelist. All domains must be valid. Up to 50 domains allowed.

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "domains_whitelist": null
}  
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
boolean
required

Id of the channel.

 
 

See general webhook documentation for instructions on how to set up webhooks for your app and further details. This section will walk you through all common webhooks as well as webhooks specific to Facebook Messenger platform.

Suggest Edits

Message Received

 

This event is fired whenever a contact sends a message to your Facebook page.

Amio Persists Message Files

All incoming messages having a file url attachments (i.e. Image Message, Video Message, etc.) are persisted on Amio servers due to expiration reasons.

{
  "event": "message_received",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!",
      "quick_reply": {
        "payload": "DEVELOPER_DEFINED_PAYLOAD"
      }
    },
    "nlp": {...}
  }
}
Parameter
Type
Description

data

object

Object representing message received. Different type of messages can be received (text, image, etc.). The structure matches Send Message response structure except for the nlp key which is valid only for received messages.

data.nlp

object

Suggest Edits

Messages Delivered

 

This event occurs when a message has been delivered to contact.

{
  "event": "messages_delivered",
  "timestamp" : "2016-10-06T13:42:48Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "messages": [
      { "id": "6456078996108088196" }, 
      { "id": "6456079002382766981" }
    ],
    "delivered_timestamp": "2016-10-06T13:40:01Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the messages were delivered.

data.messages

array

Array of messages that were delivered. Every message will contain message.id.

data.delivered_timestamp

string

Iso 8601 Timestamp. The time of message delivery to the user's device. This value may vary from webhook timestamp attribute due to delays.

Suggest Edits

Messages Read

 

This event occurs when a message has been read by the contact.

{
  "event": "messages_read",
  "timestamp" : "2016-10-06T13:42:48Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "last_read_timestamp": "2016-10-06T13:40:13Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact that has read messages delivered.

last_read_timestamp

string

Iso 8601 Timestamp

All messages that were sent before this timestamp were read. (It doesn't mean "time when the messages were read".)

Suggest Edits

Message Echo

 

Message echo event is invoked whenever message is sent to user. This callback allows you to track all messages being sent no matter if they're sent by you or by someone else. For example messages sent to Facebook users directly from Facebook Page administration can be easily recorded. The same situation can happen when you reply the user from Amio integration (i.e. you reply from Zendesk).

{
  "event": "message_echo",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our beloved customers!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
Parameter
Type
Description

data

object

Object representing message which is echoed. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body.

Suggest Edits

Postback Received

 

This callback occurs when the user presses Postback Button or Get Started Button. You can use this event to perform certain action or to reply back.

{
  "event": "postback",
  "timestamp": "2017-03-01T15:49:02.243Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "postback": {
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

payload

string

Developer-defined data set in Postback Button or Get Started Button.

Opt-in webhook is fired for several actions and is generally meant for binding a user in your application. This webhook is fired when:

Opt-in for Send to Messenger

When user presses Send to Messenger button, you will receive following webhook.

{
  "event": "opt_in",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "opt_in": {
      "type": "send_to_messenger",
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

opt_in.type

string

Describes what type of opt-in this is. In case of Send to Messenger, this will always be send_to_messenger.

opt_in.payload

string

Data set in Send to Messenger Button as data-ref attribute.

Opt-in for Checkbox

When user ticks Checkbox plugin, you will receive following webhook.

{
  "event": "opt_in",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339",
      "user_ref": "{{YOUR_CUSTOM_USER_REF}}" // set on frontend checkbox plugin
    },
    "opt_in": {
      "type": "checkbox",
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

contact.user_ref

string

Data that has been set in checkbox plugin user_ref attribute. It is should be uniquely generated string ID (unique for each render).

opt_in.type

string

Describes what type of opt-in this is. In case of Checkbox plugin, this will always be checkbox.

opt_in.payload

string

Data that has been set in checkbox plugin ref attribute.

Opt-in for Phone Number Matching

This webhook is sent when a user accepts the message request sent to his phone number using Phone Number Entry Point.

{
  "event": "opt_in",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "opt_in": {
      "type": "phone_number"
    }
  }
}
Parameter
Type
Description

contact.phone_number

string

Phone number in E.164 format.

opt_in.type

string

Describes what type of opt-in this is. In case of Phone Number Matching, this will always be phone_number.

Suggest Edits

Viber Bot

 

See Amio Documentation for getting started manuals and complete description.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify a Viber contact with one of the following attributes:

Viber Contact Id

{
  "contact": {  
    "id": "6456078781510718339"
  },
  "channel": {...},
  "content": {...}
}

You receive contact.id when the user starts a conversation with you, see Entry Points for more details.

Suggest Edits

List Messages

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id/messages
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078781510718339",
      "type": "viber"
    },
    "contact": {
      "id": "6456078759331238786"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

direction

string

Specifies if the message has been received or sent: received, sent.

sent

string

Iso 8601 Timestamp - time when the message was sent.

delivered

string

Iso 8601 Timestamp - time when the message was delivered. null means that it hasn't been delivered yet.

read

string

Iso 8601 Timestamp - time when the message was read. null means that it hasn't been read yet.

channel

object

Channel in which the message was sent or received.

contact

object

Message belongs to a contact.

content

object

Content of the message

posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "viber"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to text.

content.payload
string
required

Text to be sent. Maximum size of 320 characters.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "viber"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to image.

payload
object
payload.url
string
required

Url of the image to be sent.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "video",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "viber"
  },
  "contact": {
    "id": "6456078781510718339",
  },
  "content": {
    "type": "video",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to video.

payload
object
payload.url
string
required

Url of the video to be sent.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
 "content": {
    "type": "file",
    "payload": {
      "url": "https://example.com/file.pdf"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "viber"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "file",
    "payload": {
      "url": "https://example.com/file.pdf"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to file.

payload
object
payload.url
string
required

Url of the file to be sent.

 
Suggest Edits

Structure

Structure messages allows you to send well formatted message containing image, title, description, link and action buttons. This format is suitable when you'd like to send messages with visual content and possible call to action buttons, i.e. today's menu of your restaurant.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string

Title of the message. It is displayed on one line and the text is truncated with ellipsis (three dots in the end) if exceeds the line. You can usually fit up to 20 characters.

payload.text
string

Message text. It is displayed on 3 lines if zero or one button is used or on one line if more buttons are used. That's enough space for approximately 65 characters or 22 characters respectively.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Limitted to 3 buttons. See Buttons chapter for more details.

metadata
string

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
Suggest Edits

Structure - Horizontal Scroll

It is also possible to send multiple structured messages. They are displayed as a horizontal scroll within the Viber app.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "structure",
    "payload": [
      {
        "title": "Leaf salad",
        "text": "9.5 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-1"
          }
        ]
      },
      {
        "title": "Beef burger",
        "text": "12.0 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/9/9b/YOKOSUKA-NAVY-BURGER-TSUNAMI.JPG",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-2"
          }
        ]
      }
    ]
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "viber"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "structure",
    "payload": [
      {
        "buttons": [
          {
            "payload": "https://example.com/daily-menu/food-1",
            "type": "url",
            "title": "Show Details"
          }
        ],
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
        "item_url": "https://example.com/daily-menu",
        "text": "9.5 €",
        "title": "Leaf salad"
      },
      {
        "buttons": [
          {
            "payload": "https://example.com/daily-menu/food-2",
            "type": "url",
            "title": "Show Details"
          }
        ],
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/9/9b/YOKOSUKA-NAVY-BURGER-TSUNAMI.JPG",
        "item_url": "https://example.com/daily-menu",
        "text": "12.0 €",
        "title": "Beef burger with Coleslaw salad"
      }
    ]
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string

Title of the message. It is displayed on one line and the text is truncated with ellipsis (three dots in the end) if exceeds the line. You can usually fit up to 20 characters.

payload.text
string

Message text. It is displayed on 3 lines if zero or one button is used or on one line if more buttons are used. That's enough space for approximately 65 characters or 22 characters respectively.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Limitted to 3 buttons. See Buttons chapter for more details.

metadata
string

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
 

Buttons can be used in Structure messages. They provide the user with ability to perform a predefined action, such as opening a webpage or send a postback message.

  • Url Button
  • Postback Button

Url Button

The Url Button opens a browser with given address.

...
buttons: [
  {
    "type": "url",
    "title": "Freedom",
    "payload": "https://en.wikipedia.org/wiki/Liberty"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to url.

title*

string

Title of the button. It is displayed on one line and the text is truncated with ellipsis (three dots in the end) if exceeds the line. You can fit usually up to 18 characters.

payload*

string

Url to be opened.

Postback Button

When the user taps on the postback button, it sends developer-defined payload back on Postback Received webhook. Tapping on this button also displays the title in the Viber app. You can perform an action or reply back when this happens.

...
buttons: [
  {
    "type": "postback",
    "title": "List Items",
    "payload": "{{PASS_THROUGH_PARAM}}"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to postback.

title*

string

Title of the button. It is displayed on one line and the text is truncated with ellipsis (three dots in the end) if exceeds the line. You can fit usually up to 18 characters.

payload*

string

Any arbitrary data you can send to Postback Received webhook. Max size is 1000 characters.

 

Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
  	"any": "arbitrary data"
  }
}

Reserved metadata keywords

platform_metadata - Metadata to be sent directly to Viber API, see Platform Metadata below.

Platform Metadata

Viber API has its own concept of metadata. It's called tracking_data. You can send tracking data as a string with any message, see Viber API documentation. Amio API reserves platform_metadata keyword to be mapped to original Viber tracking_data attribute.

You can use platform_metadata attribute to send tracking data directly to Viber API. This allows you to track messages and user’s replies. Tracking data are received back as metadata.platform_metadata attribute with message replies from the user.

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
    "platform_metadata": "these data are going to be sent directly to Viber API as tracking_data attribute"
  }
}
Parameter
Type
Description

platform_metadata

string

Platform specific metadata to be sent directly to Viber API as a tracking_data attribute, see Viber API documentation. Max size 4000 characters.

 

Run in Postman

Channel represents a medium through which you can send and receive messages.

Suggest Edits

List Channels

 
gethttps://api.amio.io/v1/channels
curl --request GET \
  --url https://api.amio.io/v1/channels
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078759331238786",
    "type": "viber",
    "name": "Amio",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    },
    "viber": {
      "name": "Amio",
      "category": "Companies, Brands & Products",
      "uri": "amioio",
      "access_token": "46c9501a7eefc1ab"
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: viber.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

viber

object

Represents a Viber public account connected to the channel. You can send and receive message only If Viber is connected.

viber.name

string

Name of the Viber Bot account.

viber.category

string

Viber public account category.

viber.uri

string

String to be used for building Viber links.

viber.access_token

string

Viber Bot account access token.

Suggest Edits

Get Channel

 
gethttps://api.amio.io/v1/channels/chanel_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "viber": {
    "name": "Amio",
    "category": "Companies, Brands & Products",
    "uri": "amioio",
    "access_token": "46c9501a7eefc1ab"
  }
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: viber.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

viber

object

Represents a Viber Bot account connected to the channel. You can send and receive message only If Viber is connected.

viber.name

string

Name of the Viber Bot account.

viber.category

string

Viber Bot account category.

viber.uri

string

String to be used for building Viber links.

viber.access_token

string

Viber Bot account access token.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "url": "https://my-project.com/webhooks",
  },
  "viber": {
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "viber": {
    "name": "Amio",
    "category": "Companies, Brands & Products",
    "uri": "amioio",
    "access_token": "46c9501a7eefc1ab"
  }
}

Body Params

type
string
required

Channel type, viber.

name
string

Name of the channel. If not set, it will be filled with connected Viber Bot name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

viber
object
viber.access_token
string
required

Viber Bot account access token. It has to be unique as Viber Bot account can be assigned only to one channel. You receive this token from Viber.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: viber.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

viber

object

Represents a Viber Bot account connected to the channel. You can send and receive message only If Viber is connected.

viber.name

string

Name of the Viber Bot account.

viber.category

string

Viber Bot account category.

viber.uri

string

String to be used for building Viber links.

viber.access_token

string

Viber Bot account access token.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "Amio",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "viber": {
    "name": "Amio",
    "category": "Companies, Brands & Products",
    "uri": "amioio",
    "access_token": "46c9501a7eefc1ab"
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel. Might be an arbitrary name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

 

Remove webhook

Set webhook attribute to null if you'd like to remove channel webhook.

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: viber.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

viber

object

Represents a Viber Bot account connected to the channel. You can send and receive message only If Viber is connected.

viber.name

string

Name of the Viber Bot account.

viber.category

string

Viber Bot account category.

viber.uri

string

String to be used for building Viber links.

viber.access_token

string

Viber Bot account access token.

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel to be deleted.

 
 

Run in Postman

Contact represents the Viber user. Contact is automatically created whenever you receive a message from the user for the first time.

Suggest Edits

List Contacts

 
gethttps://api.amio.io/v1/channels/channel_id/contacts
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078781510718339",
    "name": "Dietrich Bonhoeffer",
    "locale": "de",
    "country": "DE",
    "photo_url": "https://scontent.xx.fbcdn.net/v/t1.0-1/541992_511761562179706_48931455_n.jpg?oh=1b30d9f950c70b19cf99ef8ea81a169e&oe=5A5108B3"
  }
]

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

locale

string

User’s locale.

country

string

2 letters country code - ISO ALPHA-2 Code.

photo_url

string

Url to profile picture of the user.

Suggest Edits

Get Contact

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "name": "Dietrich Bonhoeffer",
  "locale": "de",
  "country": "DE",
  "photo_url": "https://scontent.xx.fbcdn.net/v/t1.0-1/541992_511761562179706_48931455_n.jpg?oh=1b30d9f950c70b19cf99ef8ea81a169e&oe=5A5108B3"
}

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

locale

string

User’s locale.

country

string

2 letters country code - ISO ALPHA-2 Code.

photo_url

string

Url to profile picture of the user.

Suggest Edits

Delete Contact

 
deletehttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact to be deleted.

 
 

See general webhook documentation for instructions on how to set up webhooks for your app and further details. This section will walk you through all common webhooks as well as webhooks specific to Viber platform.

Suggest Edits

Message Received

 

This event is fired whenever a contact sends a message to your Viber Bot account.

Amio Persists Message Files

All incoming messages having a file url attachments (i.e. Image Message, Video Message , etc.) are persisted on Amio servers due to expiration reasons.

{
  "event": "message_received",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "viber"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!"
    },
    "nlp": {...}
  }
}
Parameter
Type
Description

data

object

Object representing message received. Different type of messages can be received (text, image, etc.). The structure matches Send Message response structure except for the nlp key which is valid only for received messages.

data.nlp

object

Suggest Edits

Messages Delivered

 

This event notifies you of messages that were delivered to your contact.

{
  "event": "messages_delivered",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "viber"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "messages": [
      { "id": "6456078996108088196" }, 
      { "id": "6456079002382766981" }
    ],
    "delivered_timestamp": "2017-12-29T17:26:16.001Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the messages were delivered.

data.messages

array

Array of messages that were delivered. Every message will contain message.id.

data.delivered_timestamp

string

Iso 8601 Timestamp. The time when Amio servers received notification about message delivery. This value may vary from webhook timestamp attribute due to delays.

Suggest Edits

Messages Read

 

This event occurs when a message has been read by the contact.

{
  "event": "messages_read",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "viber"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "last_read_timestamp": "2017-12-29T17:26:27.346Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact that has read messages delivered.

last_read_timestamp

string

Iso 8601 Timestamp

All messages that were sent before this timestamp were read. (It doesn't mean "time when the messages were read".)

Suggest Edits

Message Failed

 

This event notifies you of a message that could not be delivered to the recipient. See Viber documentation for details.

{
  "event": "message_failed",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "viber"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "message": {
      "id": "6456078996108088196"
    },
    "error": {
      "code": 1,
      "message": "Error while processing the request."
    }
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the message was sent but not delivered.

data.message

object

Messages which was sent, will contain only message.id.

data.error.code

number

Error code, see errors below.

data.error.message

string

Detail message of an error, see errors below.

Errors

Error Code
Reason

1

Error while processing the request.

2

Sending messages to this user is blocked.

3

Cannot find user for given phone number.

4

Message failed to be delivered within 24 hours.

Suggest Edits

Message Echo

 

Message echo event is invoked whenever a message is sent to a contact. This callback allows you to track all messages being sent no matter if they're sent by your channel or any other channel with the same Viber Bot account.

{
  "event": "message_echo",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "viber"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our beloved customers!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
Parameter
Type
Description

data

object

Object representing message which is echoed. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body.

Suggest Edits

Postback Received

 

This callback occurs when the user presses Postback Button. You can use this event to perform certain action or to send a reply.

{
  "event": "postback",
  "timestamp": "2017-03-01T15:49:02.243Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "viber"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "postback": {
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

payload

string

Developer-defined data set in Postback Button.

Suggest Edits

Viber Business Messages

 

See Amio Documentation for getting started manuals and complete description.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify a phone number.

Viber Phone Number

You can send a message using a phone number you already have (See Phone Number Entry Point for more details).

{
  "contact": {
    "phone_number": "+1 (555) 857-6309"
  },
  "channel": {...},
  "content": {...}
}
{
  "id": "...",
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "channel": {...},
  "content": {...}
}

Sending Message is Asynchronous

Unlike other platforms, sending messages through Viber Business Messages is asynchronous. This means the actual message is sent at some point after you receive a response to your send request.

You will receive Message Failed webhook in case given phone number is not assigned to any Viber account.

Phone Number Format

Note that the phone number in response is in E.164 format. All responses and webhooks coming from Amio use this format.

Suggest Edits

List Messages

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id/messages
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "viber_business_messages"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

direction

string

Specifies if the message has been received or sent: received, sent.

sent

string

Iso 8601 Timestamp - time when the message was sent.

delivered

string

Iso 8601 Timestamp - time when the message was delivered. null means that it hasn't been delivered yet.

read

string

Iso 8601 Timestamp - time when the message was read. null means that it hasn't been read yet.

channel

object

Channel in which the message was sent or received.

contact

object

Message belongs to a contact.

content

object

Content of the message

posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "phone_number": "+1-555-857-6309"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "viber_business_messages"
  },
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.phone_number
string
required

Phone number of the contact.

content
object
content.type
string
required

Must be set to text.

content.payload
string
required

Text to be sent. Maximum size of 1000 characters.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "phone_number": "+1-555-857-6309"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "viber_business_messages"
  },
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.phone_number
string
required

Phone number of the contact.

content
object
content.type
string
required

Must be set to image.

payload
object
payload.url
string
required

Url of the image to be sent.

 
Suggest Edits

Structure

Structure messages allows you to send well formatted message containing text with optional image and URL buttons. This format is suitable when you'd like to send messages with visual content and possible call to action buttons, i.e. today's menu of your restaurant.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "phone_number": "+1-555-857-6309"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "viber_business_messages"
	},
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.phone_number
string
required

Phone number of the contact.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string

Title of the message. Max 80 characters.

payload.text
string

Message text. Max 900 characters, text is wrapped to lines.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Viber Business Messages only support 1 button.

metadata
string

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
 

Buttons can be used in Structure messages. Viber Business Messages only allows one button per message and the button can only contain a link to a webpage.

Url Button

The Url Button opens a browser with given address.

...
buttons: [
  {
    "type": "url",
    "title": "Freedom",
    "payload": "https://en.wikipedia.org/wiki/Liberty"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to url.

title*

string

Title of the button. It is displayed on one line and the text is truncated with ellipsis (three dots in the end) if exceeds the line. You can fit usually up to 18 characters.

payload*

string

Url to be opened.

 

Developer-defined metadata can be sent with any type of message. They are delivered back in Message Echo webhook.

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
  	"any": "arbitrary data"
  }
}
 

Run in Postman

Channel represents a medium through which you can send and receive messages.

Suggest Edits

List Channels

 
gethttps://api.amio.io/v1/channels
curl --request GET \
  --url https://api.amio.io/v1/channels
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078759331238786",
    "type": "viber_business_messages",
    "name": "Viber Business Messages - Example",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    },
    "viber_business_messages": {
      "sender_id": "Example",
      "default_message_ttl": "PT24H",
      "approved": true,
      "test_mode": false
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: viber_business_messages.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

viber_business_messages

object

Contains information specific to Viber Business Messages.

viber_business_messages.sender_id

string

The Sender ID will be shown in the Viber app as a sender of the message

viber_business_messages.default_message_ttl

Message validity period. If the message couldn't be delivered within this period, it will be discarded.

viber_business_messages.approved

boolean

Messages can be sent only if the channel is approved.

viber_business_messages.test_mode

boolean

Specifies whether the Test Mode is enabled. When Test Mode is on, your Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through Viber.

Suggest Edits

Get Channel

 
gethttps://api.amio.io/v1/channels/channel_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "viber_business_messages",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "viber_business_messages": {
    "sender_id": "Example",
    "default_message_ttl": "PT24H",
    "approved": true,
    "test_mode": false
  }
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: viber_business_messages.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

viber_business_messages

object

Contains information specific to Viber Business Messages.

viber_business_messages.sender_id

string

The Sender ID will be shown in the Viber app as a sender of the message.

viber_business_messages.default_message_ttl

Message validity period. If the message couldn't be delivered within this period, it will be discarded.

viber_business_messages.approved

boolean

Messages can be sent only if the channel is approved.

viber_business_messages.test_mode

boolean

Specifies whether the Test Mode is enabled. When Test Mode is on, your Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through Viber.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "viber_business_messages",
  "name": "Amio",
  "webhook": {
    "url": "https://my-project.com/webhooks",
  },
  "viber_business_messages": {
    "sender_id": "Example"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "viber_business_messages",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "viber_business_messages": {
    "sender_id": "Example",
    "default_message_ttl": "PT24H",
    "approved": false,
    "test_mode": true
  }
}

Body Params

type
string
required

Channel type, viber_business_messages.

name
string

Name of the channel. If not set, it will be generated automatically.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

viber_business_messages
object
viber_business_messages.sender_id
string
required

The Sender ID will be shown in the Viber app as a sender of the message. You won't be able to change the Sender ID once it's registered with Viber.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: viber_business_messages.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

viber_business_messages

object

Contains information specific to Viber Business Messages.

viber_business_messages.sender_id

string

The Sender ID will be shown in the Viber app as a sender of the message

viber_business_messages.default_message_ttl

Message validity period. If the message couldn't be delivered within this period, it will be discarded.

viber_business_messages.approved

boolean

Messages can be sent only if the channel is approved.

viber_business_messages.test_mode

boolean

Specifies whether the Test Mode is enabled. For a newly created channels, it's always set to true.

When Test Mode is on, your Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through Viber.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "Amio",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "viber_business_messages": {
    "default_message_ttl": "PT20M",
    "test_mode": false
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "viber_business_messages",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "viber_business_messages": {
    "sender_id": "Example",
    "default_message_ttl": "PT20M",
    "approved": false,
    "test_mode": false
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel. Might be an arbitrary name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

viber_business_messages
object
viber_business_messages.default_message_ttl
string

Message validity period. Must be in ISO 8601 duration format. Accepted values are durations between 15 seconds and 24 hours.

viber_business_messages.test_mode
boolean

Enable/disable Test Mode. When Test Mode is on, your Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through Viber.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: viber_business_messages.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

viber_business_messages

object

Contains information specific to Viber Business Messages.

viber_business_messages.sender_id

string

The Sender ID will be shown in the Viber app as a sender of the message

viber_business_messages.default_message_ttl

Message validity period. If the message couldn't be delivered within this period, it will be discarded.

viber_business_messages.approved

boolean

Messages can be sent only if the channel is approved.

viber_business_messages.test_mode

boolean

Specifies whether the Test Mode is enabled. When Test Mode is on, your Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through Viber.

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel to be deleted.

 
 

Run in Postman

Contact represents the Viber user. Contact is automatically created whenever you send a message to new phone number.

Suggest Edits

List Contacts

 
gethttps://api.amio.io/v1/channels/channel_id/contacts
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "6456078781510718339",
        "name": "15558576309",
        "phone_number": "15558576309"
    }
]

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact. In case of Viber Business Messages, name is the same as phone number.

phone_number

string

User’s phone number (E.164 format)

Suggest Edits

Get Contact

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "name": "15558576309",
  "phone_number": "15558576309"
}

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact. In case of Viber Business Messages, name is the same as phone number.

phone_number

string

User’s phone number (E.164 format)

Suggest Edits

Delete Contact

 
deletehttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact to be deleted.

 
 

See general webhook documentation for instructions on how to set up webhooks for your app and further details. This section will walk you through all common webhooks as well as webhooks specific to Viber Business Messages platform.

Suggest Edits

Message Received

 

This event is fired whenever a reply from a contact is received.

{
  "event": "message_received",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "viber_business_messages"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!"
    },
    "nlp": {...}
  }
}
Parameter
Type
Description

data

object

Object representing message received. The structure matches Send Message response structure except for the nlp key which is valid only for received messages.

data.nlp

object

Suggest Edits

Messages Delivered

 

This event notifies you of messages that were delivered to your contact.

{
  "event": "messages_delivered",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "viber_business_messages"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "messages": [
      { "id": "6456078996108088196" }, 
      { "id": "6456079002382766981" }
    ],
    "delivered_timestamp": "2017-12-29T17:26:16.001Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the messages were delivered.

data.messages

array

Array of messages that were delivered. Every message will contain message.id.

data.delivered_timestamp

string

Iso 8601 Timestamp. The time when Amio servers received notification about message delivery. This value may vary from webhook timestamp attribute due to delays.

Suggest Edits

Messages Read

 

This event occurs when a message has been read by the contact.

{
  "event": "messages_read",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "viber_business_messages"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "last_read_timestamp": "2017-12-29T17:26:27.346Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact that has read messages delivered.

last_read_timestamp

string

Iso 8601 Timestamp

All messages that were sent before this timestamp were read. (It doesn't mean "time when the messages were read".)

Suggest Edits

Message Failed

 

This event notifies you of a message that could not be sent using phone number. This happens mostly when there is no Viber account associated with a given phone number.

{
  "event": "message_failed",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "viber_business_messages"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "message": {
      "id": "6456078996108088196"
    },
    "error": {
      "code": 3,
      "message": "Cannot find Viber user for given phone number."
    }
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the message was sent but not delivered.

data.message

object

Messages which was sent, will contain only message.id.

data.error.code

number

Error code, see errors below.

data.error.message

string

Detail message of an error, see errors below.

Errors

Error Code
Reason

1

Error while processing the request.

2

Sending messages to this user is blocked.

3

Cannot find user for given phone number.

4

Message failed to be delivered within 24 hours.

Suggest Edits

Message Echo

 

Message echo event is invoked whenever a message is sent to a contact.

{
  "event": "message_echo",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "viber_business_messages"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our beloved customers!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
Parameter
Type
Description

data

object

Object representing message which is echoed. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body.

Mobile channel is primarily used for SMS send and receive. Amio integrates with 3rd party providers which you can connect in administration and use Amio API to send messages.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify a Mobile contact with one of the following attributes:

Mobile Phone Number

{
  "contact": {  
    "id": "+1 (555) 857-6309"
  },
  "channel": {...},
  "content": {...}
}
{
  "id": "...",
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "channel": {...},
  "content": {...}
}

Phone Number Format

Note that the phone number in response is in E.164 format. All responses and webhooks coming from Amio use this format.

Suggest Edits

List Messages

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id/messages
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "mobile"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "phone_number": "+1 (555) 857-6309"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "mobile"
  },
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact. phone_number
string
required

Phone number of the contact.

content
object
content.type
string
required

Must be set to text.

content.payload
string
required

Text to be sent. Maximum length of text depends on provider (MessageBird - 1377 characters).

 
 

Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
  	"any": "arbitrary data"
  }
}
 

Run in Postman

Channel represents a medium through which you can send and receive messages.

Suggest Edits

List Channels

 
gethttps://api.amio.io/v1/channels
curl --request GET \
  --url https://api.amio.io/v1/channels
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078759331238786",
    "type": "mobile",
    "name": "Amio Mobile",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    },
    "provider": {
      "type": "messagebird",
      "sender_id": "phonenumber",
      "access_token": "r3TniW2smgLGE3ntqHT",
      "signing_key": "GDVCrN9tgECUrkouzh4gyn7k",
      "status_webhook_url": "https://api.amio.io/webhook/messagebird/status/152775927128158",
      "receive_webhook_url": "https://api.amio.io/webhook/messagebird/message/6204630442/152811200579929"
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: mobile.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

provider

object

Represents a provider used to receive and deliver messages.

provider.type

string

Name of the service provider: messagebird.

provider.sender_id

string

Phone number registered at the provider to be used as a sender number. Any string in case of using shared number.

provider.access_token

string

Access token used for authorising requests to provider.

provider.signing_key

string

Signature key used for verifying that incoming webhook came from MessageBird.

provider.status_webhook_url

string

Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.

provider.receive_webhook_url

string

Amio webhook url to be used by provider to deliver incoming SMS messages.

Suggest Edits

Get Channel

 
gethttps://api.amio.io/v1/channels/chanel_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "mobile",
  "name": "Amio Mobile",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "provider": {
    "type": "messagebird",
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k",
    "status_webhook_url": "https://api.amio.io/webhook/messagebird/status/152775927128158",
    "receive_webhook_url": "https://api.amio.io/webhook/messagebird/message/6204630442/152811200579929"
  }
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: mobile.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

provider

object

Represents a provider used to receive and deliver messages.

provider.type

string

Name of the service provider: messagebird.

provider.sender_id

string

Phone number registered at the provider to be used as a sender number. Any string in case of using shared number.

provider.access_token

string

Access token used for authorising requests to provider.

provider.signing_key

string

Signature key used for verifying that incoming webhook came from MessageBird.

provider.status_webhook_url

string

Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.

provider.receive_webhook_url

string

Amio webhook url to be used by provider to deliver incoming SMS messages.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "mobile",
  "name": "Amio Mobile",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "provider": {
    "type": "messagebird",
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "mobile",
  "name": "Amio Mobile",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "provider": {
    "type": "messagebird",
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k",
    "status_webhook_url": "https://api.amio.io/webhook/messagebird/status/152776172104684",
    "receive_webhook_url": "https://api.amio.io/webhook/messagebird/message/6204630442/152811200579929"
  }
}

Body Params

type
string
required

Channel type, mobile.

name
string

Name of the channel. If not set, it will be auto-generated.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

provider
object
provider.type
string
required

Name of the service provider. Following values are allowed: messagebird.

provider.access_token
string
required

Access token used for authorising requests to provider.

provider.signing_key
string
required

Signature key used for verifying that incoming webhook came from MessageBird. You can get this key in MessageBird administration.

provider.sender_id
string
required

Phone number registered at the provider or custom sender ID to be used as a message originator.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: mobile.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

provider

object

Represents a provider used to receive and deliver messages.

provider.type

string

Name of the service provider: messagebird.

provider.sender_id

string

Phone number registered at the provider or custom sender ID to be used as a message originator.

provider.access_token

string

Access token used for authorising requests to provider.

provider.signing_key

string

Signature key used for verifying that incoming webhook came from MessageBird.

provider.status_webhook_url

string

Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.

provider.receive_webhook_url

string

Amio webhook url to be used by provider to deliver incoming SMS messages.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "Amio",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "provider": {
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "mobile",
  "name": "Amio",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "provider": {
    "type": "messagebird",
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k",
    "status_webhook_url": "https://api.amio.io/webhook/messagebird/status/152775927128158",
    "receive_webhook_url": "https://api.amio.io/webhook/messagebird/message/6204630442/152811200579929"
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel. Might be an arbitrary name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

provider
object
provider.access_token
string

Access token used for authorising requests to provider.

provider.signing_key
string

Signature key used for verifying that incoming webhook came from MessageBird. You can get this key in MessageBird administration.

provider.sender_id
string

Phone number registered at the provider or custom sender ID to be used as a message originator.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: mobile.

name

string

Name of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

provider

object

Represents a provider used to receive and deliver messages.

provider.type

string

Name of the service provider: messagebird.

provider.sender_id

string

Phone number registered at the provider or custom sender ID to be used as a message originator.

provider.access_token

string

Access token used for authorising requests to provider.

provider.signing_key

string

Signature key used for verifying that incoming webhook came from MessageBird.

provider.status_webhook_url

string

Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.

provider.receive_webhook_url

string

Amio webhook url to be used by provider to deliver incoming SMS messages.

Remove webhook

Set webhook attribute to null if you'd like to remove channel webhook.

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel to be deleted.

 
 

Run in Postman

Contact represents the mobile number owner. Contact is automatically created whenever you send a message to new phone number or when you receive a message from the user.

Suggest Edits

List Contacts

 
gethttps://api.amio.io/v1/channels/channel_id/contacts
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078781510718339",
    "name": "15558576309",
    "phone_number": "15558576309"
  }
]

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact. Phone number by default.

phone_number

string

Phone number of the contact (E.164 format).

Suggest Edits

Get Contact

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "name": "15558576309",
  "phone_number": "15558576309"
}

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact. Phone number by default.

locale

string

Phone number of the contact (E.164 format).

Suggest Edits

Delete Contact

 
deletehttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786/contacts/6456078781510718339