Meya Bot Platform

The Meya Developer Hub

Welcome to the Meya developer hub. You'll find comprehensive guides and documentation to help you start working with Meya as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results
Suggest Edits

Getting started

Welcome to the the Meya API reference!

 

The Meya API provides external access to bot resources and services, making the platform open and extensible. The API uses REST when applicable for resources such as /users and /db and uses custom service endpoints such as /receive and /broadcast.

All API access is over HTTPS, and accessed from the https://api.meya.ai root. All data is sent and received as JSON. All endpoints require authentication using a token accessed from the Meya admin site. Access to the API varies between free and paid plans.

The Meya API also provides a set of events to which you can subscribe that will notify a URL of your choosing via Webhook.

Trying the API

All of the cURL and Python code examples have been tested to work as is. You can use the "Try it" button to test each endpoint and inpect the response and headers. This is backed by the test API bot with the api key a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3.

We have a list of endpoints and features on the left hand side which we will be adding to as we expand our API over time to provide comprehensive access.

Access your bot via API

  1. Create a Meya bot (or use an existing bot)
  2. Add an "API & Webhook" integration
  3. Note your API key (keep it private)
  4. Optionally set your Webhook URL to subscribe to events
Add the integration to your bot and go!

Add the integration to your bot and go!

Hello, world!

curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"text": "hi", "user_id": "1234567890"}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  https://api.meya.ai/receive
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/receive"
data = {"text": "hi", "user_id": "1234567890"}
auth = HTTPBasicAuth(api_key, None)

requests.post(url, json=data, auth=auth)
http -a a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  https://api.meya.ai/receive user_id=1234567890 text=hi
Suggest Edits

Authentication

 

Authenticate requests to the Meya Webhook API with an API Key (or "token") and pass it as the username of basic auth. All requests must be made over HTTPS as HTTP requests will be ignored.

curl https://api.meya.ai/PATH_TO_RESOURCE -u YOUR_API_KEY:
import requests
from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth("YOUR_API_KEY", None)
requests.get("https://api.meya.ai/PATH_TO_RESOURCE", auth=auth)
http https://api.meya.ai/PATH_TO_RESOURCE -a YOUR_API_KEY:

API keys

  • are 32 character random string of characters from the set [A-Za-z0-9]
  • are scoped to individual bots
  • should be treated as secret (do not publish on public website client-side code)
  • can be regenerated by deleting and re-adding your integration

Tip: create bots + API keys for testing

Each API key is scoped to a specific bot. You can create test bots each with their own unique API key. This is useful for testing the API.

SSL-only

All requests must be made over HTTPS as HTTP requests will be ignored.

Suggest Edits

Rate limits

How API requests are throttled

 

Meya API rate limits depend on: 1) whether or not you are on a free or paid plan and 2) which resource you are accessing.

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

curl -i https://api.meya.ai
HTTP/1.1 200 OK
Date: Mon, 13 Feb 2017 18:15:57 GMT
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 46
X-RateLimit-Reset: 17

The headers tell you everything you need to know about your current rate limit status:

Header Name
Description

X-RateLimit-Limit

The maximum number of requests that the consumer is permitted to make per hour.

X-RateLimit-Remaining

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

The amount of time (in seconds) when the rate limit window will reset

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

curl -i https://api.meya.ai
HTTP/1.1 429 TOO MANY REQUESTS
Date: Mon, 13 Feb 2017 18:25:55 GMT
Retry-After: 20

{"detail":"Request was throttled. Expected available in 20.0 seconds."}

Rate limits by resource

Resource
Free
Paid

Default

60 / minute

10,000 / minute

/broadcast

n/a

1,000 / minute

/users{/user_id}

10 / minute

1,000 / minute

/db/{table}{/object_id}

10 / minute

1,000 / minute

Suggest Edits

Status codes and errors

Response status codes and how the API deals with errors

 

Meya uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, your account isn't authorized, etc.), and codes in the 5xx range indicate an error with Meya's servers (these are rare).

HTTP status code summary

Status code
Description

200 - OK

Everything worked as expected.

201 - Created

Resource was successfully created. ex. create a new user

202 - Accepted

Request was accepted, but not yet processed. ex. /receive

204 - No content

Request was successful, but no response provided. ex. DELETE resource

400 - Bad request

The request was unacceptable, often due to missing a required parameter.

401 - Unauthorized

Unauthorized access to resource

403 - Forbidden

Invalid api key or similar

404 - Not Found

Resource doesn't exist

409 - Conflict

The request conflicts with another request. Attempting to add the same user 2x for example.

429 - Too many requests

Too many requests hit the API too quickly. We recommend an exponential backoff of your requests or upgrade to paid plan.

Suggest Edits

Current version

How changes are versioned and what previous versions exist

 

By default all requests receive the v1 version of the API. Prior beta versions of the API will be supported in a backwards compatible fashion:

Version
API root
Status

v1

https://api.meya.ai

Released: Feb. 12, 2017
Status: current

beta

https://meya.ai/webhook

Released: April 8, 2016
Status: supported
Ends: July 31, 2017

Beta API will sunset July 31, 2017

If you are using the endpoint https://meya.ai/webhook, you will need to migrate by July 31, 2017 to maintain continuous service. Please note that :bot_id is not present in v1 endpoints.

Suggest Edits

Send

Send a message to user as the bot

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/send
 curl https://api.meya.ai/send \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  -d user_id=170717261783 \
  -d integration=messenger \
  -d text=hi
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/send"
data = {
    "user_id": 170717261783,
    "integration": "messenger",
    "text": "hi"
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "ok": true
}
{
  "message": "Integration not found."
}

Body Params

meya_user_id
string

Meya user id in the format Uxxxxxxxx. If set, integration and user_id are not required.

user_id
string

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

text
string
required

Text to send the user from bot.

 
Suggest Edits

Receive

Receive an incoming message from a user

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/receive
 curl https://api.meya.ai/receive \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  -d user_id=170717261783 \
  -d integration=messenger \
  -d text=hi
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/receive"
data = {
    "user_id": 170717261783,
    "integration": "messenger",
    "text": "hi"
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "ok": true
}
{
  "detail": "Authentication credentials were not provided."
}

Body Params

meya_user_id
string

Meya user id in the format Uxxxxxxxx. If set, integration and user_id are not required.

user_id
string

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

text
string
required

The text to receive from the user to your bot.

 
Suggest Edits

Broadcast

Programmatically trigger bot broadcasts

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/broadcast
curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"flow":"hello_world", "name": "Daily hello", "profession__eq": "mathematician"}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
	https://api.meya.ai/broadcast
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/broadcast"
data = {
    "flow": "hello_world",
    "name": "Daily hello",
    "profession__eq": "mathematician"
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "ok": true,
  "user_count": 127
}
{
  "ok": false,
  "error": "Flow not found."
}

Body Params

flow
string
required

The unique flow name to trigger.

data
object

Data to pass to your flow scope.

 
action
string

Start at another state other than default

name
string

The name you want to give your broadcast for reference purposes.

send_time
date-time

The UNIX timestamp you want to schedule for the broadcast. If omitted, the broadcast will send now.

max_users
int32

The maximum number of users you want to receive your broadcast. This is to guard against sending to too many of your users.

repeat
string

The cron-formatted string for repeated broadcasts.

repeat_end
date-time

The last UNIX timestamp you want your broadcast to send (if it's a repeated broadcast). Note all times are in UTC.

mock
boolean

If set to true, a broadcast will not be sent but will do a mock request and return the number of users.

fieldname__expression
string

Add user filters for segmenting the broadcast audience. See below for examples.

 

Do not spam users

Use this feature sparingly. Do not spam users who have not opted in to receiving push broadcasts. Make sure to test your code before putting in production.

Tip: Mock before sending

set mock: true to test your queries without sending actual broadcasts. Useful to determine how many users will be impacted.

Startup plan required

You must be on the Startup plan ($49 / mo) or higher to use this feature.

Audience filter expressions

You can construct filter expressions using the syntax userfield__expression: value in order to limit your broadcast to user's who match that expression.

ex. last_name__eq: "Musk" which match all users with the last name Musk.

See the datastore for all possible filter expressions.

Suggest Edits

Button

Trigger a button click event from an interactive card in your custom app

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/button
curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"user_id": "1234567890", "message_id": "MZLQ9DchnTbxhaO8m", "type": "transition", "text": "Lionel Messi", "action": "messi", "data": {"age": 29}}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:  \
  "https://api.meya.ai/button"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
auth = HTTPBasicAuth(api_key, "")

url = "https://api.meya.ai/button"
data = {
    "user_id": "1234567890",
    "message_id": "MZLQ9DchnTbxhaO8m",
    "type": "transition",
    "text": "Lionel Messi",
    "action": "messi",
    "data": {
        "age": 29
    }
}
res = requests.post(url, json=data, auth=auth)
print res.json()
A binary file was returned
{
  "ok": true
}
{
  'message_id': [
    'This field is required.'
  ]
}

Body Params

meya_user_id
string
user_id
string
integration
string
message_id
string
required

Unique message id of the message that contains the button. ex. Mxxxxxxxxxx

type
string
required

What type of button. One of transition or start

text
string
required

The original text of the button

action
string

Required for transition button, and optional for start button

flow
string

Name of flow to invoked. Required for start button.

data
object

Data to pass to your flow scope.

 
 

Use this endpoint to simulate a button click. Use the message_id and the button payload (found at data["card"]["buttons"][idx]) as the callback when a user clicks on a button.

This endpoint is useful when integrating buttons into your own custom app.

Button validation

The text, action, flow, data, type must be consistent with the original button constructed in your flow.

Example webhook payload containing a button

Tip: Use the button JSON as the payload

You can take the button JSON payload and use as the params of the endpoint.

{
  "user_id": "1234567890",
  "sender": "bot",
  "text": "Pick your favorite football player [messi] [ronaldo]",
  "timestamp": 1491526647.888284,
  "type": "card",
  "message_id": "MkyL77cf0qmpHpZtr",
  "card": {
    "buttons": [
      {
        "messenger_extensions": null,
        "url": null,
        "text": "Lionel Messi",
        "flow": null,
        "webview_height_ratio": null,
        "image_url": null,
        "type": "transition",
        "action": "messi",
        "data": {
          "age": 29
        },
        "fallback_url": null
      },
      {
        "messenger_extensions": null,
        "url": null,
        "text": "Cristiano Ronaldo",
        "flow": null,
        "webview_height_ratio": null,
        "image_url": null,
        "type": "transition",
        "action": "ronaldo",
        "data": {
          "age": 32
        },
        "fallback_url": null
      }
    ],
    "text": "Pick your favorite football player",
    "type": "text_buttons",
    "mode": "default"
  },
  "bot_id": "BJty7evfw2b"
}
Suggest Edits

Media

Receive an incoming media upload from a user

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/media
 curl https://api.meya.ai/media \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  -d user_id=170717261783 \
  -d integration=webhook \
  -d type=audio \
  -d url=https://s3.amazonaws.com/meya-static/rooster.mp3
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/media"
data = {
    "user_id": 170717261783,
    "integration": "webhook",
    "type": "audio",
  	"url": "https://s3.amazonaws.com/meya-static/rooster.mp3"
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "ok": true
}
{
  "detail": "Authentication credentials were not provided."
}

Body Params

meya_user_id
string

Meya user id in the format Uxxxxxxxx. If set, integration and user_id are not required.

user_id
string

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

type
string
required

Must be one of: image, video, audio or file

url
string
required

Must be a valid url

 
Suggest Edits

Location

Receive incoming location coordinates from a user

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/location
 curl https://api.meya.ai/location \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  -d user_id=170717261783 \
  -d integration=webhook \
  -d lat=40.785091 \
  -d lng=-73.968285
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/location"
data = {
    "user_id": 170717261783,
    "integration": "webhook",
    "lat": 40.785091,
  	"lng": -73.968285
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "ok": true
}
{
  "detail": "Authentication credentials were not provided."
}

Body Params

meya_user_id
string

Meya user id in the format Uxxxxxxxx. If set, integration and user_id are not required.

user_id
string

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

lat
float
required
lng
float
required
 
Suggest Edits

Start flow

Start a bot flow for provided user

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/start
 curl https://api.meya.ai/start \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  -d user_id=170717261783 \
  -d integration=messenger \
  -d flow=hello_world
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/start"
data = {
    "user_id": 170717261783,
    "integration": "messenger",
    "flow": "hello_world"
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "ok": true
}
{
  "message": "Flow not found.",
  "ok": false
}

Body Params

meya_user_id
string

Meya user id in the format Uxxxxxxxx. If set, integration and user_id are not required.

user_id
string

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

flow
string
required

The unique flow name to trigger.

data
object

Data to pass to your flow scope.

 
action
string

Start at another state other than default

 
Suggest Edits

Thread pause

Pause a bot from responding to this user

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/pause
 curl https://api.meya.ai/pause \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  -d user_id=170717261783 \
  -d integration=messenger \
  -d cancel_flows=true
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/pause"
data = {
    "user_id": 170717261783,
    "integration": "messenger",
    "cancel_flows": true
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
    "active": false, 
    "ok": true
}

Body Params

meya_user_id
string

Meya user id in the format Uxxxxxxxx. If set, integration and user_id are not required.

user_id
string

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

cancel_flows
boolean

Whether or not to cancel all outstanding flows.

 

Use this API to disconnect your bot from the conversation. Can be used when a human agent has taken over the conversation or for any other reason you might want to mute the bot.

Suggest Edits

Thread unpause

Unpause bot and it will start responding to the user again

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/unpause
 curl https://api.meya.ai/unpause \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  -d user_id=170717261783 \
  -d integration=messenger
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/unpause"
data = {
    "user_id": 170717261783,
    "integration": "messenger"
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
    "active": true, 
    "ok": true
}

Body Params

meya_user_id
string

Meya user id in the format Uxxxxxxxx. If set, integration and user_id are not required.

user_id
string

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

 

Used to unpause your bot for a specific user. The is idempotent. You can safely make this call multiple times without consequence.

Suggest Edits

Thread status

Check the bot pause status for this user

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/status
 curl https://api.meya.ai/status \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  -d user_id=170717261783 \
  -d integration=messenger
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/status"
data = {
    "user_id": 170717261783,
    "integration": "messenger"
}

auth = HTTPBasicAuth(api_key, None)

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
    "active": false, 
    "ok": true
}

Body Params

meya_user_id
string

Meya user id in the format Uxxxxxxxx. If set, integration and user_id are not required.

user_id
string

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

 

Use this endpoint to determine if your bot is paused (active: false) or not.

Suggest Edits

Bot pause

Pause the bot from responding to all users

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.api/bot/pause
curl https://api.meya.ai/bot/pause \
    -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/bot/pause"
auth = HTTPBasicAuth(api_key, "")

res = requests.post(url, auth=auth)
data = res.json()
A binary file was returned
{
    "active": false,
    "within_active_hours": true,
    "ok": true
}
{
    "detail": "Invalid API key."
}
 

This will pause the bot from responding to all users

Use thread pause if you would like to only pause the bot for one user.

Note the debug logs in test chat when the bot is paused.

Note the debug logs in test chat when the bot is paused.

Suggest Edits

Bot unpause

Unpause bot and it will start responding to all users

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.api/bot/unpause
curl https://api.meya.ai/bot/unpause \
    -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/bot/unpause"
auth = HTTPBasicAuth(api_key, "")

res = requests.post(url, auth=auth)
data = res.json()
A binary file was returned
{
    "active": true,
    "within_active_hours": true,
    "ok": true
}
{
    "detail": "Invalid API key."
}
 

Thread level pause status will be unaffected

Individual users that have their bot paused, will remain paused.

Suggest Edits

Bot status

Check the bot's global pause status

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.api
curl https://api.meya.ai/bot/status \
    -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/bot/status"
auth = HTTPBasicAuth(api_key, "")

res = requests.post(url, auth=auth)
data = res.json()
A binary file was returned
{
    "active": true,
    "within_active_hours": true,
    "ok": true
}
{
    "detail": "Invalid API key."
}
 

How to tell if bot is active

The active response parameter indicates the bot pause/unpause status. This value can be set via API or bot settings.

The within_active_hours parameter indications if the bot is currently within it's active hours (for reference only configured in bot settings). For example, perhaps your bot is only active Monday - Friday, 9am to 5pm.

If either value is false then the bot will be silent.

Suggest Edits

User model

How users are represented in Meya

 

Each user that interacts with your bot will have a user object stored in your bot's database. Your bot will likely set and get data via the user scope Meya database API.

Field
Note

id
string

The Meya defined id. This is an immutable unique identifier. ex UdlY77V2tnl

user_id
string

The integration-specific user identifier. For example, Messenger PSID

integration
string

Represents the integration (chat app) that the user is communicating from. See list of integrations

...

...

{key}
string

Of type: string, integer, float, boolean, dict, list

{
  "first_name": "Kurt", 
  "last_name": "G\u00f6del", 
  "user_id": "1115412093662003", 
  "citizenship": [
    "Austrian", 
    "American"
  ], 
  "locale": "de_AT", 
  "gender": "male", 
  "profession": "mathematician", 
  "integration": "messenger", 
  "alive": false, 
  "avatar_url": "https://upload.wikimedia.org/wikipedia/en/4/42/Kurt_g%C3%B6del.jpg", 
  "timezone": -4, 
  "id": "UrxAAGBZyud", 
  "bot_id": "BA0aelClmnU"
}

Integration-specific user id

Integration
Platform
`user_id` meaning
Example `user_id`

messenger

Facebook

PSID

11154120936620030

slack

Slack

team id + user id

T138ABGQ8.U057AEGQ1

twilio

Twilio

phone number in E164

+15558675309

kik

Kik

username

kurt.godel.42

telegram

Telegram

chat id

199277562

web

Meya web chat

n/a

n/a

test

Meya test chat

n/a

n/a

intercom

Intercom

Intercom defined id

60a1df123b411efg7bfe91d9

smooch

Smooch Web, Viber, WeChat, LINE, iOS, Email, Android

Smooch _id (or userId if set) learn more

deb920657bbc3adc3fec7963

twitter

Twitter

Twitter user name

potus

webhook

Webhook

Custom

Can be any string

Suggest Edits

List users

Query users connected to your bot /w sorting, filters and pagination.

 

apiKey Auth

 Authentication is required for this endpoint.
gethttps://api.meya.ai/users
curl -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  "https://api.meya.ai/users?profession__eq=mathematician"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/users"
params = {"profession__eq": "mathematician", "limit": 1}

auth = HTTPBasicAuth(api_key, "")

res = requests.get(url, params=params, auth=auth)
data = res.json()
A binary file was returned
{
  "continuation": "NmcsMig3BigpZ2NhbxA7LjkIbXh6CAg2b2l5Yy8qLR4kIXt7bWcbCzk8biQ7Iy5zL2ck", 
  "results": [
    {
      "first_name": "Leonhard", 
      "last_name": "Euler", 
      "user_id": "170717261783", 
      "citizenship": [
        "Swiss"
      ], 
      "locale": "de_CH", 
      "gender": "male", 
      "profession": "mathematician", 
      "integration": "messenger", 
      "alive": false, 
      "avatar_url": "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg", 
      "timezone": 1, 
      "id": "UbotM497MQw", 
      "bot_id": "BJty7evfw2b"
    }, 
    {
      "first_name": "Kurt", 
      "last_name": "G\u00f6del", 
      "user_id": "1115412093662003", 
      "citizenship": [
        "Austrian", 
        "American"
      ], 
      "locale": "de_AT", 
      "gender": "male", 
      "profession": "mathematician", 
      "integration": "messenger", 
      "alive": false, 
      "avatar_url": "https://upload.wikimedia.org/wikipedia/en/4/42/Kurt_g%C3%B6del.jpg", 
      "timezone": -4, 
      "id": "UrxAAGBZyud", 
      "bot_id": "BJty7evfw2b"
    }
  ]
}
{
  "limit": [
    "Ensure this value is less than or equal to 100."
  ]
}

Query Params

limit
int32

Limit the number of results per page.

order_by
array of strings

Order results. use -column for descending sort.

continuation
string

A continuation token returned from a previous response. Used for paging.

profession__eq
string

This is an example filter only. This is of the form field__expression Learn more

 

Paging

If continuation token is present, that means there is more paged data. You can use this token as the continuation token in subsequent requests to page through the data.

Filtering

You can add any number of filter expressions to query your data. For example, the query parameter profession__eq=mathematician will only return users who are mathematicians. See the full list of valid filter expressions.

Sorting

Results can be sorted by using a list of columns to the order_by parameter. Use "-column" for DESC sort. For example, order_by=last_name&order_by=-age will sort by last_name ASC then by age DESC

Sorting with multiple pages

When using order_by please note that Meya doesn't guarantee ordering if there are more than 1 page of results.

No results found

If there are no users who match the query, results: [] will be returned with status code 200.

Suggest Edits

Create user

Create a user connected to your bot

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/users
curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"avatar_url": "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg", "alive": false, "first_name": "Leonhard", "gender": "male", "integration": "messenger", "last_name": "Euler", "locale": "de_CH", "profession": "mathematician", "timezone": 1, "user_id": "170717261783x", "citizenship": ["Swiss"]}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:  \
  "https://api.meya.ai/users"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/users"
data = {
    "avatar_url":
        "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg",
    "alive": False,
    "first_name": "Leonhard",
    "gender": "male",
    "integration": "messenger",
    "last_name": "Euler",
    "locale": "de_CH",
    "profession": "mathematician",
    "timezone": 1,
    "user_id": "170717261783",
    "citizenship": ["Swiss"]
}

auth = HTTPBasicAuth(api_key, "")

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "first_name": "Leonhard", 
  "last_name": "Euler", 
  "user_id": "170717261783", 
  "citizenship": [
    "Swiss"
  ], 
  "locale": "de_CH", 
  "gender": "male", 
  "profession": "mathematician", 
  "integration": "messenger", 
  "alive": false, 
  "avatar_url": "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg", 
  "timezone": 1, 
  "id": "UbotM497MQw", 
  "bot_id": "BJty7evfw2b"
}
{
  'message': 'User exists.'
}

Body Params

user_id
string
required

Integration specific user id. Learn more

integration
string

String representation of the integration Learn more

field
string

Example only. Replace field with one or more fields to update.

 
Suggest Edits

Retrieve user

Returns a single user object if it exists

 

apiKey Auth

 Authentication is required for this endpoint.
gethttps://api.meya.ai/users/user_id
curl -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  "https://api.meya.ai/users/UbotM497MQw"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/users/UbotM497MQw"
auth = HTTPBasicAuth(api_key, "")

res = requests.get(url, auth=auth)
data = res.json()
curl -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  "https://api.meya.ai/users/messenger:170717261783"
A binary file was returned
{
  "first_name": "Leonhard", 
  "last_name": "Euler", 
  "user_id": "170717261783", 
  "citizenship": [
    "Swiss"
  ], 
  "locale": "de_CH", 
  "gender": "male", 
  "profession": "mathematician", 
  "integration": "messenger", 
  "alive": false, 
  "avatar_url": "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg", 
  "timezone": 1, 
  "id": "UbotM497MQw", 
  "bot_id": "BJty7evfw2b"
}
{
  "message": "User not found."
}

Path Params

user_id
string
required

One of: Meya-defined user id OR concatenation of integration:user_id Learn more

 
Suggest Edits

Update user

Update a sub-set user fields. Leave other fields untouched.

 

apiKey Auth

 Authentication is required for this endpoint.
patchhttps://api.meya.ai/users/user_id
curl -H "Content-Type: application/json" \
  -X PATCH \
  -d '{"identity": "e^(pi * i) = -1", "born": "15 April 1707", "age": 76}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:  \
  "https://api.meya.ai/users/UbotM497MQw"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/users/UbotM497MQw"
data = {
    "identity": "e^(pi * i) = -1",
    "born": "15 April 1707",
    "age": 76,
}
auth = HTTPBasicAuth(api_key, "")

res = requests.patch(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "first_name": "Leonhard", 
  "last_name": "Euler", 
  "user_id": "170717261783", 
  "citizenship": [
    "Swiss"
  ], 
  "locale": "de_CH", 
  "gender": "male", 
  "age": 76, 
  "profession": "mathematician", 
  "integration": "messenger", 
  "alive": false, 
  "born": "15 April 1707", 
  "avatar_url": "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg", 
  "test": "ecdfaegaeg", 
  "timezone": 1, 
  "id": "UbotM497MQw", 
  "identity": "e^(pi * i) = -1", 
  "bot_id": "BJty7evfw2b"
}
{"message":"User not found."}

Path Params

user_id
string
required

One of: Meya-defined user id OR concatenation of integration:user_id Learn more

Body Params

field
string

Example only. Replace field with one or more fields to update.

 
Suggest Edits

Overwrite user

Completely overwrite user with new data.

 

apiKey Auth

 Authentication is required for this endpoint.
puthttps://api.meya.ai/users/user_id
curl -H "Content-Type: application/json" \
  -X PUT \
  -d '{"avatar_url": "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg", "alive": false, "first_name": "Leonhard", "gender": "male", "last_name": "Euler", "locale": "de_CH", "profession": "mathematician", "timezone": 1, "citizenship": ["Swiss"]}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:  \
  "https://api.meya.ai/users/UxWjhUrnRBN"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/users/UxWjhUrnRBN"
data = {
    "avatar_url":
        "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg",
    "alive": False,
    "first_name": "Leonhard",
    "gender": "male",
    "last_name": "Euler",
    "locale": "de_CH",
    "profession": "mathematician",
    "timezone": 1,
    "citizenship": ["Swiss"]
}
auth = HTTPBasicAuth(api_key, "")

res = requests.put(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "first_name": "Leonhard", 
  "last_name": "Euler", 
  "user_id": "170717261783", 
  "citizenship": [
    "Swiss"
  ], 
  "locale": "de_CH", 
  "gender": "male", 
  "profession": "mathematician", 
  "integration": "messenger", 
  "alive": false, 
  "avatar_url": "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg", 
  "timezone": 1, 
  "id": "UxWjhUrnRBN", 
  "bot_id": "BJty7evfw2b"
}
{"message":"User not found."}

Path Params

user_id
string
required

One of: Meya-defined user id OR concatenation of integration:user_id Learn more

Body Params

field
string

Example only. Replace field with one or more fields to update.

 

Be careful!

PUT will overwrite all data for the given user. Consider using PATCH to update some fields, while leaving others untouched.

Suggest Edits

Delete user

Delete a user object and it's associated bot conversation history.

 

apiKey Auth

 Authentication is required for this endpoint.
deletehttps://api.meya.ai/users/user_id
curl -X DELETE \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  "https://api.meya.ai/users/UWlOnxGhm21"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/users/UWlOnxGhm21"
auth = HTTPBasicAuth(api_key, "")

res = requests.delete(url, auth=auth)
A binary file was returned
  
{
  "message":"User not found."
}

Path Params

user_id
string
required

One of: Meya-defined user id OR concatenation of integration:user_id Learn more

 

Be careful!

Once deleted, the data associated with the user is gone forever. If the user interacts with the bot again, a new user object will be created.

Suggest Edits

Object model

Store generic data using Meya's table scope database

 

Meya also provides a database for storing general object data. This data is stored in table scope datastore (read more). Objects are stored in table and are assigned a unique object_id.

Object examples

  • orders (timestamp, price, item)
  • tickets (issue, user)
  • menu items (item, ingredients, price)
  • products (SKU, name, description, price, image_url)
  • category (name, parent)
  • settings (key, val)
Field
Note

id
string

The immutable unique identifier generated by Meya. ex. O4PTHV5E87T

...

...

{key}
string

Of type: string, integer, float, boolean, dict, list

{
  "name": "pizza Margherita",
  "ingredients": [
    "crust",
    "tomato sauce",
    "mozzarella",
    "basil"
  ],
  "price": 11.25,
  "image_url": "http://imgur.com/cIf35KH",
  "id": "O4PTHV5E87T",
  "bot_id": "BJty7evfw2b"
}

Accessing objects from bot

This data can be accessed from your bot component code:

pizza = self.db.table("food").get("O4PTHV5E87T")
Suggest Edits

List objects

Query list of objects /w sorting, filters and pagination.

 

apiKey Auth

 Authentication is required for this endpoint.
gethttps://api.meya.ai/db/table
curl -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  "https://api.meya.ai/db/food?limit=2&name__contains=Ma"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/db/food"
params = {"name__contains": "Ma", "limit": 2}

auth = HTTPBasicAuth(api_key, "")

res = requests.get(url, params=params, auth=auth)
data = res.json()
A binary file was returned
{
  "continuation": null,
  "results": [
    {
      "name": "pizza Margherita",
      "ingredients": [
        "crust",
        "tomato sauce",
        "mozzarella",
        "basil"
      ],
      "price": 11.25,
      "image_url": "http://imgur.com/cIf35KH",
      "id": "O4PTHV5E87T",
      "bot_id": "BJty7evfw2b"
    },
    {
      "name": "Big Mac",
      "ingredients": [
        "2 all beef patties",
        "special sauce",
        "lettuce",
        "onion",
        "sesame seed bun"
      ],
      "price": 3.99,
      "image_url": "http://i.imgur.com/UM1bL5F.jpg",
      "id": "OM5P9TKMJYP",
      "bot_id": "BJty7evfw2b"
    }
  ]
}
{
  "limit": [
    "Ensure this value is less than or equal to 100."
  ]
}

Path Params

table
string
required

Query Params

limit
string

Limit the number of results per page.

order_by
string

Order results. Use -column for descending sort.

continuation
string

A continuation token returned from a previous response. Used for paging.

name__eq
string

This is an example filter only. This is of the form field__expression Learn more

 

Paging

If continuation token is present, that means there is more paged data. You can use this token as the continuation token in subsequent requests to page through the data.

Filtering

You can add any number of filter expressions to query your data. For example, the query parameter profession__eq=mathematician will only return users who are mathematicians. See the full list of valid filter expressions.

Sorting

Results can be sorted by using a list of columns to the order_by parameter. Use "-column" for DESC sort. For example, order_by=last_name&order_by=-age will sort by last_name ASC then by age DESC

Sorting with multiple pages

When using order_by please note that Meya doesn't guarantee ordering if there are more than 1 page of results.

No results found

If there are no users who match the query, results: [] will be returned with status code 200.

Suggest Edits

Create object

Create a new object in a table in the Meya database

 

apiKey Auth

 Authentication is required for this endpoint.
posthttps://api.meya.ai/db/table
curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"name": "pizza Margherita", "price": 11.25, "image_url": "http://imgur.com/cIf35KH", "ingredients": ["crust", "tomato sauce", "mozzarella", "basil"]}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:  \
  "https://api.meya.ai/db/food"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/db/food"
data = {
  "name": "pizza Margherita",
  "price": 11.25,
  "image_url": "http://imgur.com/cIf35KH",
  "ingredients": [
    "crust",
    "tomato sauce",
    "mozzarella",
    "basil"
  ]
}

auth = HTTPBasicAuth(api_key, "")

res = requests.post(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "name": "pizza Margherita",
  "ingredients": [
    "crust",
    "tomato sauce",
    "mozzarella",
    "basil"
  ],
  "price": 11.25,
  "image_url": "http://imgur.com/cIf35KH",
  "id": "O4PTHV5E87T",
  "bot_id": "BJty7evfw2b"
}
{
  "parameter": "name",
  "message": "String exceeds 4096 characters"
}

Path Params

table
string
required

The name of the table where the object is stored

Body Params

field
string

Example only. Replace field with one or more fields to update.

 
Suggest Edits

Retrieve object

Returns a single object if it exists

 

apiKey Auth

 Authentication is required for this endpoint.
gethttps://api.meya.ai/db/table/object_id
curl -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3: \
  "https://api.meya.ai/db/food/O4PTHV5E87T"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/db/food/O4PTHV5E87T"
auth = HTTPBasicAuth(api_key, "")

res = requests.get(url, auth=auth)
data = res.json()
A binary file was returned
{
  "name": "pizza Margherita",
  "ingredients": [
    "crust",
    "tomato sauce",
    "mozzarella",
    "basil"
  ],
  "price": 11.25,
  "image_url": "http://imgur.com/cIf35KH",
  "id": "O4PTHV5E87T",
  "bot_id": "BJty7evfw2b"
}
{
  "message": "Object not found."
}

Path Params

table
string
required

The name of the table where the object is stored

object_id
string
required

The unique object id assigned by Meya

 
Suggest Edits

Update object

Update a sub-set object fields. Leave other fields untouched.

 

apiKey Auth

 Authentication is required for this endpoint.
patchhttps://api.meya.ai/db/table/object_id
curl -H "Content-Type: application/json" \
  -X PATCH \
  -d '{"rating": 4.9}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:  \
  "https://api.meya.ai/db/food/O4PTHV5E87T"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/db/food/O4PTHV5E87T"
data = {"rating": 4.9}
auth = HTTPBasicAuth(api_key, "")

res = requests.patch(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "rating": 4.9,
  "name": "pizza Margherita",
  "ingredients": [
    "crust",
    "tomato sauce",
    "mozzarella",
    "basil"
  ],
  "price": 11.25,
  "image_url": "http://imgur.com/cIf35KH",
  "id": "O4PTHV5E87T",
  "bot_id": "BJty7evfw2b"
}
{
  "message": "Object not found."
}

Path Params

table
string
required

The name of the table where the object is stored

object_id
string
required

The unique object id assigned by Meya

Body Params

field
string

Example only. Replace field with one or more fields to update.

 
Suggest Edits

Overwrite object

Completely overwrite object with new data.

 

apiKey Auth

 Authentication is required for this endpoint.
puthttps://api.meya.ai/db/table/object_id
curl -H "Content-Type: application/json" \
  -X PUT \
  -d '{"name": "Big Mac", "price": 3.98, "image_url": "http://i.imgur.com/UM1bL5F.jpg", "ingredients": ["2 all beef patties", "special sauce", "lettuce", "onion", "sesame seed bun"]}' \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:  \
  "https://api.meya.ai/db/food/OJZ3TWGNNHZ"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/db/food/OJZ3TWGNNHZ"
data = {
  "name": "Big Mac",
  "price": 3.98,
  "image_url": "http://i.imgur.com/UM1bL5F.jpg",
  "ingredients": [
    "2 all beef patties",
    "special sauce",
    "lettuce",
    "onion",
    "sesame seed bun"
  ]
}
auth = HTTPBasicAuth(api_key, "")

res = requests.put(url, json=data, auth=auth)
data = res.json()
A binary file was returned
{
  "name": "Big Mac",
  "ingredients": [
    "2 all beef patties",
    "special sauce",
    "lettuce",
    "onion",
    "sesame seed bun"
  ],
  "price": 3.98,
  "image_url": "http://i.imgur.com/UM1bL5F.jpg",
  "id": "OJZ3TWGNNHZ",
  "bot_id": "BJty7evfw2b"
}
{
  "message": "Object not found."
}

Path Params

table
string
required

The name of the table where the object is stored

object_id
string
required

The unique object id assigned by Meya

Body Params

field
string

Example only. Replace field with one or more fields to update.

 

Be careful!

PUT will overwrite all data for the given user. Consider using PATCH to update some fields, while leaving others untouched.

Suggest Edits

Delete object

Delete an object from a database table

 

apiKey Auth

 Authentication is required for this endpoint.
deletehttps://api.meya.ai/db/table/object_id
curl -i -H "Content-Type: application/json" \
  -X DELETE \
  -u a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3:  \
  "https://api.meya.ai/db/food/OPUS1DRSPNP"
import requests
from requests.auth import HTTPBasicAuth


api_key = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"
url = "https://api.meya.ai/db/food/OPUS1DRSPNP"
auth = HTTPBasicAuth(api_key, "")

res = requests.delete(url, auth=auth)
A binary file was returned
  
{
  "message": "Object not found."
}

Path Params

table
string
required

The name of the table where the object is stored

object_id
string
required

The unique object id assigned by Meya

 

Be careful!

Once deleted, the object is gone forever.

Suggest Edits

Overview

The basics of subscribing to Meya event webhooks

 

You can use webhooks to receive notifications about events such as message delivery, users created and objects modified.

In order to handle these events, you register a "Webhook URL" with the "API & Webhook" integration and choose which events to subscribe to.

Interested in integrating Meya in to your own app?

See the custom app integration section. You will need to subscribe to the text and (optionally) typing events.

List of events

Event
Description
Status

text

Sent when a user message is received or a bot message is sent. Useful for creating custom app integrations. link

Currently only applies to webhook integration

typing

Sent when typing indicator is turned on or off by the bot.
link

Currently only applies to webhook integration

user

Sent when user scope data is created, modified, or deleted link

Paid plan required

table

Sent when table scope data is created, modified, or deleted link

Paid plan required

Missing something?

We will be expanding the number of events that you can subscribe to over time. Please contact bots@meya.ai or reach out on Slack if you have a specific use-case in mind.

How events are sent

When an event in your subscription occurs we'll send an HTTP POST request to your Webhook URL saved with your API & Webhook integration. The event will be in the Content-Type: application/json format:

{
    "user_id": "1234567890",
    "sender": "bot|user",
    "timestamp": 1487101588.395739,
    "type": "type_of_event",
    "bot_id": "Bxxxxxxx",
    "event_specific_field": "value"
}

Responding to events

Your app should respond to the event request with an HTTP 2xx within three seconds. If it does not, we'll consider the event delivery attempt failed.

No retries

Currently, Meya will not retry on webhook delivery failure.

We recommend responding to events with a HTTP 200 OK as soon as you can. You may want to avoid processing and reacting to events within the same process handling event reception.

Setup your webhook URL and event subscriptions

Setup your webhook URL and event subscriptions

Suggest Edits

User events

Sent when user scope data is created, modified, or deleted.

 

If subscribed, whenever a user is created, modified or deleted in the context of a bot flow, bot component or Meya API, a user event will be sent to your Webhook URL.

Use-cases:

  • keep user databases in sync
  • event-based workflows

Startup plan required

You must be on the Startup plan ($49 / mo) or higher to use this feature.

User event object

Field
Description

type
string

Always user

bot_id
string

The id of the bot associated with the data ex. BJty7evfw2b

user_id
string

Not used. Always null

sender
string

Always bot

timestamp
float

UNIX timestamp of the change to 5 decimal precision. ex 1487093050.56191

operation
string

One of insert, modify, remove

user
object

The up-to-date user model

{
    "user_id": null,
    "user": {
        "first_name": "Leonhard",
        "last_name": "Euler",
        "user_id": null,
        "citizenship": [
            "Swiss"
        ],
        "locale": "de_CH",
        "gender": "male",
        "profession": "mathematician",
        "integration": null,
        "alive": false,
        "avatar_url": "https://upload.wikimedia.org/wikipedia/commons/d/d7/Leonhard_Euler.jpg",
        "id": "UxWjhUrnRBN",
        "bot_id": "BJty7evfw2b"
    },
    "timestamp": 1487093050.56191,
    "operation": "modify",
    "bot_id": "BJty7evfw2b",
    "type": "user",
    "sender": "bot"
}

Debug mode

If debug mode is turned on in your API & Webhook integration on Meya admin, test chat user events will be sent as well.

Suggest Edits

Database events

Sent when table scope data is created, modified, or deleted.

 

If subscribed, whenever an object is created, modified or deleted in the context of a bot flow, bot component or Meya API, a table event will be sent to your Webhook URL.

Use-cases:

  • keep object databases in sync
  • event-based workflows

Startup plan required

You must be on the Startup plan ($49 / mo) or higher to use this feature.

User event object

Field
Description

type
string

Always table

bot_id
string

The id of the bot associated with the data ex. BJty7evfw2b

user_id
string

Not used. Always null

sender
string

Always bot

timestamp
float

UNIX timestamp of the change to 5 decimal precision. ex 1487093050.56191

operation
string

One of insert, modify, remove

object
object

The up-to-date object model

table
string

Table name where the object resids. ex food

{
    "user_id": null,
    "sender": "bot",
    "timestamp": 1487092324.516319,
    "object": {
        "name": "Big Mac",
        "ingredients": [
            "2 all beef patties",
            "special sauce",
            "lettuce",
            "onion",
            "sesame seed bun"
        ],
        "price": 3.98,
        "image_url": "http://i.imgur.com/UM1bL5F.jpg",
        "id": "O4PTHV5E87T",
        "bot_id": "BJty7evfw2b"
    },
    "table": "food",
    "operation": "modify",
    "type": "table",
    "bot_id": "BJty7evfw2b"
}
Suggest Edits

Message events

When a message is received or sent via the webhook integration

 

You can subscribe to bot and user message text events.

Use-cases:

Webhook integration-only

Only messages received or sent to the webhook integration will be delivered to this webhook.

{
    "user_id": "roger.waters",
    "sender": "user",
    "timestamp": 1487101585.943187,
    "text": "hi",
    "type": "text",
    "bot_id": "BJty7evfw2b"
}
{
    "user_id": "roger.waters",
    "sender": "bot",
    "timestamp": 1487101587.398373,
    "text": "Hello, World!",
    "type": "text",
    "bot_id": "BJty7evfw2b"
}

User initiated messages

If you would like to also receive user-initiated messages, you'll have to enable that setting in your webhook. In the case of a user initiated message sender will come in as user rather than bot.

Select "Send user initiated messages?" to receive user messages as well.

Select "Send user initiated messages?" to receive user messages as well.

Suggest Edits

Typing events

Sent when typing indicator is turned on or off by the bot for the webhook integration

 

You can subscribe to typing indicator on and off events.

Use-cases:

Webhook integration-only

Only messages received or sent to the webhook integration will be delivered to this webhook.

{
    "status": "on",
    "user_id": "roger.waters",
    "sender": "bot",
    "timestamp": 1487101588.73427,
    "type": "typing",
    "bot_id": "BJty7evfw2b"
}
{
    "status": "off",
    "user_id": "roger.waters",
    "sender": "bot",
    "timestamp": 1487101588.395739,
    "type": "typing",
    "bot_id": "BJty7evfw2b"
}
Suggest Edits

Security

How to ensure HTTP requests are coming from the Meya Bot Platform

 

In order to ensure that requests are coming from Meya Bot Platform and not a malicious third party, we have included a cryptographic signature.

This works very similar to how Twilio security works.

How Meya signs requests to your server

  1. Meya appends JSON body /w sorted keys, and spaces removed to the end of the URL (with no delimiter)
  2. Meya takes the resulting string (the full URL with query string and the raw body) and signs it using HMAC-SHA1 and your api_key as the key.
  3. Meya sends this signature in an HTTP header called X-Meya-Signature

How to verify the signature

  1. Take the full URL of the request and append the JSON body /w sorted keys, and spaces removed as a string
  2. Sign the resulting string with HMAC-SHA1 using your api_key as the key
  3. Base64 encode the resulting hash value
  4. Compare your hash to ours, submitted in the X-Meya-Signature header. If they match, then you've verified that Meya is the originator

Example headers

POST /yourpath HTTP/1.1
Host: yourdomain.com
Accept-Encoding: gzip, deflate
Accept: application/json
User-Agent: python-requests/2.13.0
X-Meya-Signature: Wrl+9YX4ok2RI0VAugSwKcVWgto=
Content-Type: application/json
Content-Length: 130
X-Forwarded-Proto: https
X-Forwarded-For: 52.91.53.134

How to verify signature

from hashlib import sha1
import hmac
import json

API_KEY = "a6xE5yLe0RHPYbiHqR3OKDmRgsZ76RY3"

"""
Verify with the following data:
url = "https://203f31bb.ngrok.io/rx/apibot"
body = '{"user_id": "1234567890", "sender": "user", "timestamp": 1489843997.625053, "text": "hi", "type": "text", "bot_id": "BJty7evfw2b"}'
signature = "Wrl+9YX4ok2RI0VAugSwKcVWgto="
"""

def standardize_json_string(raw_body):
  # ensure sorted keys and no separators
  data = json.loads(raw_body)
  return json.dumps(data, sort_keys=True, separators=(',', ':'))


def validate(request):
	url = request.url
	message = standardize_json_string(request.body)
  signature = request.headers.get('X-Meya-Signature')

  data = str(url + message)
  hashed = hmac.new(API_KEY, data, sha1)
  computed_signature = hashed.digest().encode("base64").rstrip('\n')

  return computed_signature == signature
Suggest Edits

Filter expressions

How to construct valid filter expressions when querying lists of data

 

The usage for conditional expressions is field__condition. So for example, price__lt=100 finds all rows where price < 100. price is the field and lt is the expression.

https://api.meya.ai/users?profession__eq=mathematician
https://api.meya.ai/db/food?name__contains=Mac
{
  "profession__eq": "mathematician"
}

See the making queries section of the docs. API filter expressions follow the same rules and patterns.

Suggest Edits

Custom app integration

You can use API and webhook events to integrate Meya into your own app

 

Outside of the popular messaging app integrations, you can create a custom integration with your own app or service via the Webhook API. This API can be used to:

  1. Receive messages from your users to your Meya bot
  2. Send bot messages to your Webhook URL (https://yourdomain.com/path)
Webhook API Architecture

Webhook API Architecture