Suggest Edits

/messageBot

/messageBot is used to initiate or continue a conversation from a human with one of your bots.

 
gethttps://api.motion.ai/messageBot
curl --request GET \
  --url 'https://api.motion.ai/messageBot?bot=bot&msg=msg&session=session&key=key'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.motion.ai/messageBot',
  qs: 
   { bot: 'bot',
     msg: 'msg',
     session: 'session',
     key: 'key' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.motion.ai/messageBot?bot=bot&msg=msg&session=session&key=key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.motion.ai/messageBot?bot=bot&msg=msg&session=session&key=key");

xhr.send(data);
import requests

url = "https://api.motion.ai/messageBot"

querystring = {"bot":"bot","msg":"msg","session":"session","key":"key"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

bot
int32
required

Specifies the bot ID you would like to communicate with

msg
string
required

The human message to the bot

session
string
required

The session ID for this conversation. Can be any string (such as an IP address hash or session ID from your own system)

key
string
required

Your API key from https://dashboard.motion.ai/profile#api

from
string

You may optionally define who the message is "from" (i.e., a unique identifier for the user)

 

You can use this API to both initiate and reply/continue conversations from your users to a bot.

The session parameter should be any identifying factor you would like to use - for example, the hash of a user's IP or an existing session ID from your own service.

A note on Session Persistance

By default, sessions expire after 100 seconds. You can define a different number in the Settings for your bot.

The response from this API contains the bot's reply (botResponse) to your inputted message (msg). To traverse through a conversation flow, continue making requests, swapping out msg with a pertinent reply to the bot's response.

Determining the end of a flow

If you reach a dead-end or the end of a conversation flow, the value of botResponse will be null.

Suggest Edits

/messageHuman

/messageHuman is used to initiate or continue a conversation with a human from one of your bots, outside of the normal conversation flow you've defined.

This is particularly useful when you wish to initiate a flow of conversation based on an internal event that has taken place...For example, conducting a customer survey 3 days after someone uses your service.

 
posthttps://api.motion.ai/messageHuman
curl --request POST \
  --url https://api.motion.ai/messageHuman
var request = require("request");

var options = { method: 'POST', url: 'https://api.motion.ai/messageHuman' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.motion.ai/messageHuman")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.motion.ai/messageHuman");

xhr.send(data);
import requests

url = "https://api.motion.ai/messageHuman"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

to
string
required

Depending on the bot type: an human's SMS phone number, email, Facebook Recipient ID or session ID. See below for more information.

bot
int32
required

The bot ID from which to send

key
string
required

Your API key from https://dashboard.motion.ai/profile#api

msg
string

The message to send to the human (one of msg or startModule is required)

startModule
int32

The module from which to start in the flow (one of msg or startModule is required)

quickReplies
array of strings

Optionally, an array of strings, each a suggested/quick reply button

cards
array

Optionally, an array of Card objects (for supported bot mediums). See below for more information.

cardType
string

Optionally, the type of template to use for cards, either "generic" (horizontal) or "list" (vertical)

globalButtons
array

Optionally, for the "list" cardType, a single Button object within an array. Displays below the list of card items.

 

The "to" parameter

Determining a valid "to" parameter

The to parameter should contain a value representing where the human can be reached. The value of to will depend on the medium your bot inhabits (Facebook, Slack, SMS or Email).

Below are the medium-specific criteria for constructing valid to parameters.

Slack

For Slack bots, the to parameter should be a channel name prepended by a # symbol, for example: #engineering.

Email

For email bots, the to parameter should contain a valid email address, for example: hello@motion.ai

SMS

For SMS bots, the to parameter should simply be an SMS-capable 11-digit US telephone number, for example: 15551231234

Webchat

For webchat bots, the to parameter should be a session value from a webchat URL, for example: user_123.

Smooch

For Smooch bots, the to parameter should be the the user id from Smooch, for example: 13c9924269c2122beca7cc5b.

Facebook Messenger

For Facebook Messenger bots, the to parameter should contain the Facebook User's Recipient ID. Please note that the recipient ID is not the same as a traditional Facebook User ID. To find the recipient ID, visit the Conversations view of your account. The recipient ID is highlighted in yellow in the screenshot below.

Sending Cards

Messenger Webchat

If your bot is deployed as a Facebook Messenger or Webchat bot, you may include Cards to be displayed to the message recipient. To do this, specify a cards parameter as an array of Card objects in your API request along with optional parameters cardType and globalButtons.

{
  "cards": [
    // Card 1
    {
      cardTitle: 'TestMessageHumanTitle', // Card Title
      cardSubtitle: 'TestMessageHumanSubtitle', // Card Subtitle
      cardImage: 'https://www.motion.ai/images/logo_molecules_gradient.png', // Source URL for image
      cardLink: 'https://www.motion.ai', // Click through URL
      buttons: [{
        buttonText: 'MessageHumanButton 1', // Button Call to Action
        buttonType: 'webview', // 'module', 'url', 'webview', 'element_share', or 'phone_number'
        webviewHeight: 'compact', // 'compact', 'tall', or 'full'
        target:  'https://dashboard.motion.ai'// // Message text, URL, or phone number
      }]
    },
    // Card 2
    {
      cardTitle: 'TestMessageHumanTitle2',
      cardSubtitle: 'TestMessageHumanSubtitle2',
      cardImage: 'https://www.motion.ai/images/logo_molecules_gradient.png',
      cardLink: 'https://www.motion.ai',
      buttons: [{
        buttonText: 'MessageHumanButton 2',
        buttonType: 'url',
        target:  'https://dashboard.motion.ai'
      }]
    },
    // And so on...
  ],
  
  // Optional settings for Facebook Messenger bots
  
  cardType: "generic", // either 'generic' or 'list'
  
  // Used for 'list' cards (maximum of 1 per message)
  globalButtons: [{
    buttonText: 'GlobalButton 1', // Button Call to Action
  	buttonType: 'webview', // 'module', 'url', 'webview', 'element_share', or 'phone_number'
    webviewHeight: 'compact', // 'compact', 'tall', or 'full'
  	target:  'https://dashboard.motion.ai' // Message text, URL, or phone number
	}]
}
Suggest Edits

/getConversations

/getConversations can be used to retrieve messages from your account in bulk.

 
gethttps://api.motion.ai/1.0/getConversations
curl https://api.motion.ai/1.0/getConversations?key=YOUR_API_KEY&direction=in
A binary file was returned

You couldn't be authenticated

{
    "code": 200,
    "messageCount": 1000,
    "messages": [
        {
            "text": "how",
            "from": "0a7d1f0d28ec7608cff289d75f6f5f0b",
            "to": "180",
            "updated_at": "2016-05-18T15:49:09.092Z",
            "session": "0a7d1f0d28ec7608cff289d75f6f5f0b",
            "module": 5922,
            "botID": 180,
            "botNickname": "Motion AI",
            "botType": "webchat",
            "direction": "in",
            "archived": false
        },
        {
            "text": "what",
            "from": "0a7d1f0d28ec7608cff289d75f6f5f0b",
            "to": "180",
            "updated_at": "2016-05-18T15:49:14.130Z",
            "session": "0a7d1f0d28ec7608cff289d75f6f5f0b",
            "module": 5922,
            "botID": 180,
            "botNickname": "Motion AI",
            "botType": "webchat",
            "direction": "in",
            "archived": false
        },
        {
            "text": "when",
            "from": "0a7d1f0d28ec7608cff289d75f6f5f0b",
            "to": "180",
            "updated_at": "2016-05-18T15:49:15.650Z",
            "session": "0a7d1f0d28ec7608cff289d75f6f5f0b",
            "module": 5922,
            "botID": 180,
            "botNickname": "Motion AI",
            "botType": "webchat",
            "direction": "in",
            "archived": false
        },
......

Query Params

key
string
required

Your API key from https://dashboard.motion.ai/profile#api

botID
int32

Optionally, you may specify a bot ID to retrieve messages sent/received by that specific bot.

botType
string

Optionally, specify a single medium to filter messages by. fb,slack,webchat,email,sms

session
string

Optionally, you may filter conversations by session ID. To retrieve a session ID, first make a request to this API without specifying a session and locate a message from your desired session, where you'll find a session variable.

module
int32

Optionally, you may filter conversations by module ID.

direction
string

in or out - do not specify anything if you wish to include both inbound and outbound messages

archived
boolean

true will include messages previously archived on https://dashboard.motion.ai/conversations... If false, it will only return unarchived messages.

limit
int32

Optionally, limit the number of results returned (maximum: 1000)

skip
int32

Optionally, skip through returned results for pagination

 
Suggest Edits

Webhooks

If you have defined a webhook (either for your entire account, or for a specific module connection), we will POST to your server each time your bot sends or receives a message. You also have the opportunity to respond with JSON and ingest custom variables or cards to a conversation flow (see documentation below)

 
posthttp://yourwebhook.com/
curl --request POST \
  --url http://yourwebhook.com/
var request = require("request");

var options = { method: 'POST', url: 'http://yourwebhook.com/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://yourwebhook.com/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://yourwebhook.com/");

xhr.send(data);
import requests

url = "http://yourwebhook.com/"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available

Form Data

from
string

The sender of the message

to
string

The recipient of the message

reply
string

The message text that was, or will be, sent.

replyData
string

Extracted data from the message (i.e., "yes" or "no" if it were a Sentiment module)

botID
int32

The ID of the bot sending/receiving the message.

moduleID
int32

The ID of the module for the current message

session
string

The conversation session ID the message belongs to

direction
string

in or out

attachedMedia
string

Contains a URL to any media that was attached by an end-user in their reply.

 

Setting custom variables in your server's response

Messenger Webchat Slack Smooch Email SMS API

If you would like to ingest custom variables into the conversation (such as an order ID number or personal info you have for the user), you may respond to the webhook request with JSON containing key/value sets.

{ "key1": "value1", "key2": "value2" }

If your server responded with the text above, Motion AI would ingest key1 and key2 into the active conversation session. If your bot had modules containing [[key1]] or [[key2]], the text would be replaced with the values you ingested.

This is particularly useful for situations where you have existing data about your users that you would like to import to a conversation flow.

You may also invoke custom variables as a condition for module connects. For more information, see Custom Variables.

Overriding bot messages in your server's response

To override your bot's next message, return a responseOverride value in your webhook response.

{ "responseOverride" : "Some generic override message." }

Setting Cards in your server's response

Messenger Webchat

If your bot is deployed as a Messenger or Webchat bot, you may include Cards to be displayed in the bot's following reply. To do this, specify a cards object in your server's response body.

{
  "cards": [
    // Card 1
    {
      cardTitle: 'TestWebhookTitle', // Card Title
      cardSubtitle: 'TestWebhookSubtitle', // Card Subtitle
      cardImage: 'https://www.motion.ai/images/logo_molecules_gradient.png', // Source URL for image
      cardLink: 'https://www.motion.ai', // Click through URL
      buttons: [{
        buttonText: 'WebhookButton 1', // Button Call to Action
        buttonType: 'webview', // 'module', 'url', 'webview', 'element_share', or 'phone_number' (depends on bot medium)
        webviewHeight: 'compact' // 'compact', 'tall', or 'full'
        target:  'https://dashboard.motion.ai' // Message text, URL, or phone number
      }]
    },
    // Card 2
    {
      cardTitle: 'TestWebhookTitle2',
      cardSubtitle: 'TestWebhookSubtitle2',
      cardImage: 'https://www.motion.ai/images/logo_molecules_gradient.png',
      cardLink: 'https://www.motion.ai',
      buttons: [{
        buttonText: 'WebhookButton 2',
        buttonType: 'url',
        target:  'https://dashboard.motion.ai'
      }]
    },
    // And so on...
  ],
  
  // Optional settings for Facebook Messenger bots
  
  cardType: "generic", // either 'generic' or 'list'
  
  // Used for 'list' cards (maximum of 1 per message)
  globalButtons: [{
    buttonText: 'GlobalButton 1', // Button Call to Action
  	buttonType: 'webview', // 'module', 'url', 'webview', 'element_share', or 'phone_number' (depends on bot medium)
    webviewHeight: 'compact', // 'compact', 'tall', or 'full'
  	target:  'https://dashboard.motion.ai' // Message text, URL, or phone number
	}]
}

The response above (without optional Messenger settings) would result in the following Cards being displayed: