NAV Navbar
Logo
shell java python csharp php javascript

Introduction

The nativeMsg API allows you to have a single two-way connection for all your messaging needs.

Our goal is to make it as easy as possible to enable messaging across all supported channels for your application. Our REST-based endpoints give you the ability to send and receive messages, create conversational bots and integrate with third party CRM, support or sales applications.

API Token

To interact with the nativeMsg API, you must obtain an API token from your account. Please login and go to Settings to generate an API token. Copy this token and store it in a secure place. These tokens never expire.

Example Token: NMVj2JR3mqaY63TqqkjTyhshKKjs4mlPkMvG2vYz9fNMH8UzO5FFnHPcvD0xcQY4r0b2yr0cDooLM4cQ05RL9xUd96hUqh

Authentication

Requests to the nativeMsg API are authenticated using JSON Web Tokens. You must add an Authorization header using the Bearer schema to every request made to the API. The content of the header should look like this:

Authorization: Bearer $TOKEN

Endpoint

All API requests should be made to the following URL. The call for each individual resource should be appended to this URL.

https://api.nativemsg.com/v1/

Request and Response Formats

JSON payload

{
  "text": "Hello World!",
  "media": "http://example.com/images/logo.png",
  "mediaType": "image",
  "script": "",
  "targets": [
    {
      "targetType":"humans",
      "tags":"scientists,teachers",
      "ids":[31,32,33]
    }
  ]
}

Successful JSON Response

200 OK

{
  "attribute1":"data1",
  "attribute2":"data2"
}

Error JSON Response

{
  "code": "422",
  "reasonPhrase": "Unprocessable Entity",
  "description": "The server understands the content type of the request entity and the syntax of the request entity is correct but was unable to process the contained instructions.",
  "homeRef":"https://api.nativemsg.com",
  "contactEmail":"support@nativemsg.com",
  "uri":"http://www.webdav.org/specs/rfc2518.html#STATUS_422"
}

All requests will be sent via HTTP GET, POST, PUT or DELETE.

Content-Type: application/json

All HTTP Responses will be in a JSON format like the following:

Successful Response

A successful response will return a HTTP 200 OK and a JSON object. For HTTP DELETE methods, an empty JSON object will be returned.

Error Response

Parameter Description
code The HTTP status code returned
reasonPhrase Short description of the status code
description Full description of the error
homeRef The base URL that processed the request
contactEmail The support email you can contact for help
uri A URL to the WEBDAV definition of the HTTP Status code

HTTP Status Codes

All requests will return one of the following HTTP status codes in the response.

Code Error Status Description
200 OK Everything went as planned.
400 Client Error Bad Request Something in your header or request body was malformed.
401 Client Error Unauthorized Necessary credentials were either missing or invalid.
403 Client Error Forbidden Your credentials are valid but you don’t have access to the requested resource.
404 Client Error Not Found Item does not exist.
408 Client Error Request Timeout Sent by the server when an HTTP client opens a connection, but has never sent a request (or never sent the blank line that signals the end of the request).
409 Client Error Error conflict The request could not be completed due to a conflict with the current state of the resource
413 Client Error Request Entity Too Large The server is refusing to process a request because the request entity is larger than the server is willing or able to process.
416 Client Error Requested Range Not Satisfiable The client has asked for a range of the data, but the server cannot supply that range.
422 Client Error Unprocessable Entity This status code means the server understands the content type of the request entity (syntactically correct) but was unable to process the contained instructions.
429 Client Error Too Many Requests The server refuses to accept the request because the user has sent too many requests in a given amount of time.
500 Server Error Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.
502 Server Error Bad Gateway The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.
503 Server Error Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
504 Server Error Gateway Timeout The server, while acting as a gateway or proxy, could not connect to the upstream server.

Channel Types

Channel Type Request:

curl "https://api.nativemsg.com/v1/channels/types"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/channels/types");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/channels/types", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/channels/types");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels/types");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels/types',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Channel Type Response:

[
  {
    "name":"fb",
    "description":"Facebook"
  },
  {
    "name":"sky",
    "description":"Skype"
  },
  {
    "name":"slk",
    "description":"Slack"
  }
]

NativeMsg offers or will offer a number of connections into popular messaging applications and services. These include channels like native SMS/MMS, third party apps like Facebook, Slack, Skype, etc. and voice interfaces like Amazon Alexa, Google Home, etc.

Our Channel Type endpoint lists the currently offered channels. The channel type name will be used as an identifier in other API calls.

HTTP GET Request

GET https://api.nativemsg.com/v1/channels/types

Get Channel Type List Response

Parameter Description
name The name of the Channel Type. This will be the identifier used in other API calls.
description The full name description of the messaging Channel Type.

Available Channels

Name Description
fb Facebook
tus Text Us Plugin
sms SMS text messaging
mms MMS messaging
twr Twitter
alx Alexa Skill
tlg Telegram - coming soon
sky Skype - coming soon
slk Slack - coming soon

Flows

A Flow is a logical grouping of channels. A Flow allows you to setup different rules, responses, actions and bots for different messaging channels. You will assign one to many messaging channels to a flow and then create rules that govern that flow for your user base.

Flow Properties

A list of various object and properties used when working with a flow.

Flow Object Properties

Parameter Description
id The id of the Flow
name The name of the flow (100 characters max)
description The description of the flow (500 characters max)
totalMessages The total amount of messages sent and received for this flow.
totalHumans The total number of humans who have interacted with this flow.
totalTextUsClicks The total number of clicks on the Text Us plugin. (Optional) This will only show if the value is greater than zero.
dateCreated The date and time the flow was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
greetingText Greeting text for new conversations. It is only rendered the first time the human interacts with the channel. Personalization tags are supported.
welcomeMessage A welcome Message Object that will be automatically sent to a human before a new conversation is started. Supported by Twitter channel type.
getStartedButton A Get Started Button Object with the configuration of Get Started button.
persistentMenu A Persistent Menu Object with the configuration of Persistent Menu.
botId Reference to a Bot that will be executed each time a Human sends a message.
botEnabled Indicates whether a bot is enabled or not for this flow.
connectedChannelTypes An array with names of connected Channel Types.

Personalization

Get Started Button Object Properties

Parameter Description
payload The value for the pressed button that will be send back to the webhook (1,000 character max).
execute The name of the interaction/action that will be executed when the button is tapped.

Persistent Menu Object Properties

Parameter Description
items An array of the Persistent Menu Item Objects. Menu item list is limited to 5 items.

Persistent Menu Item Object Properties

Parameter Description
title The title of the menu item (30 characters max). Required.
url The full URL that will be opened in a browser when the button is tapped. Can’t be used with payload property or with nested items.
payload The value for the pressed button that will be send back to the webhook (1,000 character max). Can’t be used with url property or with nested items.
execute The name of the interaction/action that will be executed when the button is tapped. Can’t be used with url property or with nested items.
items An array of the Persistent Menu Item Objects. Menu can have at most 3 hierarchical levels.

Get a List of Flows

Flow List Request:

curl "https://api.nativemsg.com/v1/flows"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/flows");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/flows", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/flows");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/flows");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/flows',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Flow List Response:

200 OK

[
  {
    "id":123112,
    "name":"Video Release Flow",
    "description":"All inbound video call-to-actions",
    "totalMessages":123412,
    "totalHumans":567812,
    "totalTextUsClicks":65434,
    "dateCreated": "2017-02-24T18:00:44",
    "greetingText":"Hello {{user_first_name}}, thanks for checking us out.",
    "welcomeMessage": null,
    "getStartedButton":
      {
        "payload":"greenButton",
        "execute":"green"
      },
    "persistentMenu":
      {
        "items":
        [
          {
            "title":"Website",
            "url":"http://nativemsg.com"
          },
          {
            "title": "Support",
            "payload": "supportOption",
            "execute": "support"
          }
        ]
      },
    "connectedChannelTypes": 
      [
        "fb"
      ]    
  },
]

The endpoint will return an array of flows for your account.

HTTP GET Request

GET https://api.nativemsg.com/v1/flows

Get Flows List Response

Parameter Description
id The id of the flow
name The name of the flow (100 characters max)
description The description of the flow (500 characters max)
totalMessages The total amount of messages sent and received for this flow.
totalHumans The total number of humans who have interacted with this flow.
totalTextUsClicks The total number of clicks on the Text Us plugin. (Optional) This will only show if the value is greater than zero.
dateCreated The date and time the flow was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
greetingText Greeting text for new conversations. It is only rendered the first time the human interacts with the channel.
welcomeMessage A welcome Message Object that will be automatically sent to a human before a new conversation is started. Supported by Twitter channel type.
getStartedButton A Get Started Button Object with the configuration of Get Started button.
persistentMenu A Persistent Menu Object with the configuration of Persistent Menu.
botId Reference to a bot that will be executed each time human sends a message.
botEnabled Indicates whether a bot is enabled or not for this flow.
connectedChannelTypes An array with names of connected Channel Types.

Get a Flow

Flow Request:

curl "https://api.nativemsg.com/v1/flows/123112"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/flows/123112");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/flows/123112", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/flows/123112");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/flows/123112");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/flows/123112',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Flow Response:

200 OK

{
  "id":123112,
  "name":"Video Release Flow",
  "description":"All inbound video call-to-actions",
  "totalMessages":123412,
  "totalHumans":567812,
  "totalTextUsClicks":65434,
  "dateCreated": "2017-02-24T18:00:44",
  "connectedChannelTypes": 
    [
      "fb"
    ]
}

The endpoint will get a single flow by id.

HTTP GET Request

GET https://api.nativemsg.com/v1/flows/{flow_id}

Get Flow Response

Parameter Description
id The id of the Flow
name The name of the flow (100 characters max)
description The description of the flow (500 characters max)
totalMessages The total amount of messages sent and received for this flow.
totalHumans The total number of humans who have interacted with this flow.
totalTextUsClicks The total number of clicks on the Text Us plugin. (Optional) This will only show if the value is greater than zero.
dateCreated The date and time the flow was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
greetingText Greeting text for new conversations. It is only rendered the first time the human interacts with the channel.
welcomeMessage A welcome Message Object that will be automatically sent to a human before a new conversation is started. Supported by Twitter channel type.
getStartedButton A Get Started Button Object with the configuration of Get Started button.
persistentMenu A Persistent Menu Object with the configuration of Persistent Menu.
botId Reference to a bot that will be executed each time human sends a message.
botEnabled Indicates whether a bot is enabled or not for this flow.
connectedChannelTypes An array with names of connected Channel Types.

Add a New Flow

Add Flow Request:

curl "https://api.nativemsg.com/v1/flows"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"name\":\"A New Flow\",
      \"description\":\"A new flow created via API call\"}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/flows");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"name\": \"A New Flow\"," +
            "\"description\": \"A new flow created via API call\"" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "name": "A New Flow",
    "description": "A new flow created via API call"
}"""
connection.request("POST", "/v1/flows", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""name"": ""A New Flow"",
            ""description"": ""A new flow created via API call""
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/flows", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/flows");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'A New Flow',
    'description' => 'A new flow created via API call'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/flows',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    name: 'A New Flow',
    description: 'A new flow created via API call'
}));
request.end();

Add Flow Response:

200 OK

{
  "id":56345,
  "name":"A New Flow",
  "description":"A new flow created via API call",
  "totalMessages":0,
  "totalHumans":0,
  "totalTextUsClicks":0,
  "dateCreated": "2017-02-24T18:00:44"
}

This endpoint will add a new flow to your account.

HTTP POST Request

POST https://api.nativemsg.com/v1/flows

POST JSON Payload

Parameter Description
name The name of the flow (100 characters max). Required.
description The description of the flow (500 characters max)

The successful creation of a new Flow will return the Flow object below.

POST Flow Response

Parameter Description
id The id of the flow
name The name of the flow (100 characters max)
description The description of the flow (500 characters max)
totalMessages The total amount of messages sent and received for this flow.
totalHumans The total number of humans who have interacted with this flow.
totalTextUsClicks The total number of clicks on the Text Us plugin. (Optional) This will only show if the value is greater than zero.
dateCreated The date and time the flow was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
greetingText Greeting text for new conversations. It is only rendered the first time the human interacts with the channel.
welcomeMessage A welcome Message Object that will be automatically sent to a human before a new conversation is started. Supported by Twitter channel type.
getStartedButton A Get Started Button Object with the configuration of Get Started button.
persistentMenu A Persistent Menu Object with the configuration of Persistent Menu.
botId Reference to a bot that will be executed each time human sends a message.
botEnabled Indicates whether a bot is enabled or not for this flow.
connectedChannelTypes An array with names of connected Channel Types.

Update a Flow

Update Flow Request:

curl "https://api.nativemsg.com/v1/flows/56345"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X PUT
  -d "{\"name\":\"An Updated Flow\",
      \"description\":\"Changed the flow via API call\"}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPut request = new HttpPut("https://api.nativemsg.com/v1/flows/56345");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"name\": \"An Updated Flow\"," +
            "\"description\": \"Changed the flow via API call\"" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "name": "An Updated Flow",
    "description": "Changed the flow via API call"
}"""
connection.request("PUT", "/v1/flows/56345", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""name"": ""An Updated Flow"",
            ""description"": ""Changed the flow via API call""
        }";

    var response = await client.PutAsync("https://api.nativemsg.com/v1/flows/56345", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/flows/56345");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'An Updated Flow',
    'description' => 'Changed the flow via API call'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/flows/56345',
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    name: 'An Updated Flow',
    description: 'Changed the flow via API call'
}));
request.end();

Update Flow Response:

200 OK

{
  "id":56345,
  "name":"An Updated Flow",
  "description":"Changed the flow via API call",
  "totalMessages":123412,
  "totalHumans":567812,
  "totalTextUsClicks":65434,
  "dateCreated": "2017-02-24T18:00:44"
}

This endpoint will update an existing flow.

HTTP PUT Request

PUT https://api.nativemsg.com/v1/flows/{flow_id}

PUT JSON Payload

Parameter Description
name The name of the flow (100 characters max)
description The description of the flow (500 characters max)

At least one payload field is required. The successful update of a Flow will return the updated Flow object below.

PUT Flow Response

Parameter Description
id The id of the flow
name The name of the flow (100 characters max)
description The description of the flow (500 characters max)
totalMessages The total amount of messages sent and received for this flow.
totalHumans The total number of humans who have interacted with this flow.
totalTextUsClicks The total number of clicks on the Text Us plugin. (Optional) This will only show if the value is greater than zero.
dateCreated The date and time the flow was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
greetingText Greeting text for new conversations. It is only rendered the first time the human interacts with the channel.
welcomeMessage A welcome Message Object that will be automatically sent to a human before a new conversation is started. Supported by Twitter channel type.
getStartedButton A Get Started Button Object with the configuration of Get Started button.
persistentMenu A Persistent Menu Object with the configuration of Persistent Menu.
botId Reference to a bot that will be executed each time human sends a message.
botEnabled Indicates whether a bot is enabled or not for this flow.
connectedChannelTypes An array with names of connected Channel Types.

Delete a Flow

Delete Flow Request:

curl "https://api.nativemsg.com/v1/flows/56345"
  -H "Authorization: Bearer <API_TOKEN>"
  -X DELETE
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpDelete request = new HttpDelete("https://api.nativemsg.com/v1/flows/56345");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("DELETE", "/v1/flows/56345", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.DeleteAsync("https://api.nativemsg.com/v1/flows/56345");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/flows/56345");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/flows/56345',
    method: 'DELETE',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Delete Flow Response:

200 OK

{}

This endpoint will delete an existing flow.

HTTP DELETE Request

DELETE https://api.nativemsg.com/v1/flows/{flow_id}

DELETE Flow Response

A successful deletion will return an HTTP 200 OK response.

Channels

A Channel is a connection to a messaging destination. This could be Facebook Messenger, native SMS/MMS, Slack, Telegram, etc. A Channel provides the connection to send and receive messages from your users. Depending on the channel, you must provide the required credentials to connect the channel. The required credentials per channel are outlined below.

Get a List of Channels

List Channels Request:

curl "https://api.nativemsg.com/v1/channels?flow_id=4345"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/channels?flow_id=4345");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/channels?flow_id=4345", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/channels?flow_id=4345");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels?flow_id=4345");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels?flow_id=4345',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

List Channels Response:

200 OK

[
  {
    "id":123112,
    "channelType":"fb",
    "flowId":123133,
    "name":"xyz.com Facebook Page",
    "description":"XYZ Web Property",
    "user":"234234234123",
    "phoneType":1,
    "countryCode":"US",
    "dateCreated": "2017-02-24T18:00:44"
  },
]

The endpoint will return an array of channels for the given flow id.

HTTP GET Request

GET https://api.nativemsg.com/v1/channels

Get Channels Properties

Parameter Description
flow_id A flow id to filter the channel list. (Optional)

Get Channels List Response

Parameter Description
id The id of the channel
channelType The channel type (fb, tus, sms, etc)
flowId The id of the flow for this channel
name The name of the channel (255 characters max)
description The description of the channel (200 characters max)
user The public identifier for this channel. This is the Page Id for Facebook.
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now
dateCreated The date and time the channel was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Get a Channel

Channel Request:

curl "https://api.nativemsg.com/v1/channels/56435"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/channels/56435");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/channels/56435", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/channels/56435");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels/56435");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels/56435',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Channel Response:

200 OK

{
  "id":56435,
  "channelType":"fb",
  "flowId":123133,
  "name":"xyz.com Facebook Page",
  "user":"234234234123",
  "phoneType":0,
  "countryCode":null,
  "description":"XYZ Web Property",
  "dateCreated": "2017-02-24T18:00:44"
}

The endpoint will get a single channel by id.

HTTP GET Request

GET https://api.nativemsg.com/v1/channels/{channel_id}

Get Channel Response

Parameter Description
id The id of the channel
channelType The type of channel (fb, tus, sms, etc)
flowId The id of the flow for this channel
name The name of the channel (255 characters max)
description The description of the channel (200 characters max)
user The public identifier for this channel. This is the Page Id for Facebook.
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now
dateCreated The date and time the channel was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Add a Channel

Add Channel Request:

curl "https://api.nativemsg.com/v1/channels"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"channelType\":\"fb\",
      \"flowId\":123133,
      \"name\":\"XYZ Brand FB Page\",
      \"description\":\"XYZ Brand Web Property FB Page\",
      \"user\":\"8273428734\",
      \"token\":\"asdjfaskjflkasjdflasjdfl\"}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/channels");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"channelType\": \"fb\"," +
            "\"flowId\": 123133," +
            "\"name\": \"XYZ Brand FB Page\"," +
            "\"description\": \"XYZ Brand Web Property FB Page\"," +
            "\"user\": \"8273428734\"," +
            "\"token\": \"asdjfaskjflkasjdflasjdfl\"" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "channelType": "fb",
    "flowId": 123133,
    "name": "XYZ Brand FB Page",
    "description": "XYZ Brand Web Property FB Page",
    "user": "8273428734",
    "token": "asdjfaskjflkasjdflasjdfl"
}"""
connection.request("POST", "/v1/channels", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""channelType"": ""fb"",
            ""flowId"": 123133,
            ""name"": ""XYZ Brand FB Page"",
            ""description"": ""XYZ Brand Web Property FB Page"",
            ""user"": ""8273428734"",
            ""token"": ""asdjfaskjflkasjdflasjdfl""
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/channels", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'channelType' => 'fb',
    'flowId' => 123133,
    'name' => 'XYZ Brand FB Page',
    'description' => 'XYZ Brand Web Property FB Page',
    'user' => '8273428734',
    'token' => 'asdjfaskjflkasjdflasjdfl'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    channelType: 'fb',
    flowId: 123133,
    name: 'XYZ Brand FB Page',
    description: 'XYZ Brand Web Property FB Page',
    user: '8273428734',
    token: 'asdjfaskjflkasjdflasjdfl'
}));
request.end();

Add Channel Response:

200 OK

{
  "id":121222,
  "channelType":"fb",
  "flowId":123133,
  "name":"XYZ Brand FB Page",
  "description":"XYZ Brand Web Property FB Page",
  "user":"8273428734",
  "phoneType":0,
  "countryCode":null,
  "dateCreated": "2017-02-24T18:00:44"
}

This endpoint will add a new channel to a flow.

HTTP POST Request

POST https://api.nativemsg.com/v1/channels

POST JSON Payload

Parameter Description
channelType The type of channel (fb, tus, sms, etc)
flowId The id of the flow for this channel
name The name of the channel (255 characters max)
description The description of the channel (200 characters max)
user The public identifier for this channel. This is the Page Id for Facebook.
token The password, private key or token for this channel. This is the Page Access Token for Facebook.
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now

The successful creation of a new Channel will return the Channel object below.

POST Channel Response

Parameter Description
id The id of the channel
channelType The type of channel (fb, tus, sms, etc)
flowId The id of the flow for this channel
name The name of the channel (255 characters max)
description The description of the channel (200 characters max)
user The public identifier for this channel. This is the Page Id for Facebook.
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800 - Text Us channel only
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now - Text Us channel only
dateCreated The date and time the channel was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Update a Channel

Update Channel Request:

curl "https://api.nativemsg.com/v1/channels/121222"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X PUT
  -d "{\"channelType\":\"fb\",
      \"flowId\":123133,
      \"name\":\"XYZ Updated FB Page\",
      \"description\":\"XYZ Brand Web Property FB 2\",
      \"user\":\"8273428734\",
      \"token\":\"asdjfaskjflkasjdflasjdfl\"}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPut request = new HttpPut("https://api.nativemsg.com/v1/channels/121222");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"channelType\": \"fb\"," +
            "\"flowId\": 123133," +
            "\"name\": \"XYZ Updated FB Page\"," +
            "\"description\": \"XYZ Brand Web Property FB 2\"," +
            "\"user\": \"8273428734\"," +
            "\"token\": \"asdjfaskjflkasjdflasjdfl\"" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "channelType": "fb",
    "flowId": 123133,
    "name": "XYZ Updated FB Page",
    "description": "XYZ Brand Web Property FB 2",
    "user": "8273428734",
    "token": "asdjfaskjflkasjdflasjdfl"
}"""
connection.request("PUT", "/v1/channels/121222", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""channelType"": ""fb"",
            ""flowId"": 123133,
            ""name"": ""XYZ Updated FB Page"",
            ""description"": ""XYZ Brand Web Property FB 2"",
            ""user"": ""8273428734"",
            ""token"": ""asdjfaskjflkasjdflasjdfl""
        }";

    var response = await client.PutAsync("https://api.nativemsg.com/v1/channels/121222", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels/121222");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'channelType' => 'fb',
    'flowId' => 123133,
    'name' => 'XYZ Updated FB Page',
    'description' => 'XYZ Brand Web Property FB 2',
    'user' => '8273428734',
    'token' => 'asdjfaskjflkasjdflasjdfl'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels/121222',
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    channelType: 'fb',
    flowId: 123133,
    name: 'XYZ Updated FB Page',
    description: 'XYZ Brand Web Property FB 2',
    user: '8273428734',
    token: 'asdjfaskjflkasjdflasjdfl'
}));
request.end();

Update Channel Response:

200 OK

{
  "id":121222,
  "channelType":"fb",
  "flowId":123133,
  "name":"XYZ Updated FB Page",
  "description":"XYZ Brand Web Property FB 2",
  "user":"8273428734",
  "phoneType":0,
  "countryCode":null,
  "dateCreated": "2017-02-24T18:00:44"
}

This endpoint will update an existing channel.

HTTP PUT Request

PUT https://api.nativemsg.com/v1/channels/{channel_id}

PUT JSON Payload

Parameter Description
channelType The type of channel (fb, tus, sms, etc)
flowId The id of the flow for this channel
name The name of the channel (255 characters max)
description The description of the channel (200 characters max)
user The public identifier for this channel. This is the Page Id for Facebook.
token The password, private key or token for this channel. This is the Page Access Token for Facebook.

The successful update of a Channel will return the updated Channel object below.

PUT Channel Response

Parameter Description
id The id of the channel
channelType The type of channel (fb, tus, sms, etc)
flowId The id of the flow for this channel
name The name of the channel (255 characters max)
user The public identifier for this channel. This is the Page Id for Facebook.
description The description of the channel (200 characters max)
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800 - Text Us channel only
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now - Text Us channel only
dateCreated The date and time the channel was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Delete a Channel

Delete Channel Request:

curl "https://api.nativemsg.com/v1/channels/121222"
  -H "Authorization: Bearer <API_TOKEN>"
  -X DELETE
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpDelete request = new HttpDelete("https://api.nativemsg.com/v1/channels/121222");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("DELETE", "/v1/channels/121222", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.DeleteAsync("https://api.nativemsg.com/v1/channels/121222");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels/121222");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels/121222',
    method: 'DELETE',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Delete Channel Response:

200 OK

{}

This endpoint will delete an existing Channel.

HTTP DELETE Request

DELETE https://api.nativemsg.com/v1/channels/{channel_id}

DELETE Channel Response

A successful deletion will return an HTTP 200 OK response.

Subscribe Humans to a Channel

Subscribe Humans to a Channel Request:

curl "https://api.nativemsg.com/v1/channels/551/subscribe"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"humanIds\": [540, 542]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/channels/551/subscribe");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"humanIds\": [" +
                "540," +
                "542" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "humanIds": [
        540,
        542
    ]
}"""
connection.request("POST", "/v1/channels/551/subscribe", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""humanIds"": [
                540,
                542
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/channels/551/subscribe", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels/551/subscribe");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'humanIds' => [
        540,
        542
    ]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels/551/subscribe',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    humanIds: [
        540,
        542
    ]
}));
request.end();

Subscribe Humans to a Channel Response:

200 OK

{
    "channelId": 551,
    "subscribedHumansCount": 2
}

This endpoint will subscribe specified humans to their channel.

HTTP POST Request

POST https://api.nativemsg.com/v1/channels/<channel_id>/subscribe

POST JSON Payload

Parameter Description
humanIds Array of human ids that need to be subscribed to their channel.

The successful subscription of humans to a channel will return the object below.

HTTP POST Response

Parameter Description
channelId The id of the channel.
subscribedHumansCount The number of affected humans that were subscribed to the channel.

Unsubscribe Humans from a Channel

Unsubscribe Humans from a Channel Request:

curl "https://api.nativemsg.com/v1/channels/551/unsubscribe"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"humanIds\": [540, 542]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/channels/551/unsubscribe");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"humanIds\": [" +
                "540," +
                "542" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "humanIds": [
        540,
        542
    ]
}"""
connection.request("POST", "/v1/channels/551/unsubscribe", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""humanIds"": [
                540,
                542
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/channels/551/unsubscribe", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels/551/unsubscribe");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'humanIds' => [
        540,
        542
    ]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels/551/unsubscribe',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    humanIds: [
        540,
        542
    ]
}));
request.end();

Unsubscribe Humans from a Channel Response:

200 OK

{
    "channelId": 551,
    "unsubscribedHumansCount": 2
}

This endpoint will unsubscribe specified humans from their channel.

HTTP POST Request

POST https://api.nativemsg.com/v1/channels/<channel_id>/unsubscribe

POST JSON Payload

Parameter Description
humanIds Array of human ids that need to be unsubscribed from their channel.

The successful unsubscription of humans from a channel will return the object below.

HTTP POST Response

Parameter Description
channelId The id of the channel.
unsubscribedHumansCount The number of affected humans that were unsubscribed from the channel.

Get a Channel Subscription Status

Get a Channel Subscription Status Request:

curl "https://api.nativemsg.com/v1/channels/551/subscription"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/channels/551/subscription");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/channels/551/subscription", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/channels/551/subscription");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/channels/551/subscription");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/channels/551/subscription',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Get a Channel Subscription Status Response:

200 OK

{
    "channelId": 551,
    "subscribedHumansCount": 2
}

The endpoint will get a channel subscription status.

HTTP GET Request

GET https://api.nativemsg.com/v1/channels/<channel_id>/subscription

HTTP GET Response

Parameter Description
channelId The id of the channel.
subscribedHumansCount The number of humans that are subscribed to the channel.

Bots

A Bot is a list of rules, logic and messages (Interactions) that processes incoming messages on the Channels of a particular Flow. A Flow will use these automated rules and responses to interact with a Human via a messaging channel.

A Bot is made up of several key components or elements:

Notes

Some properties support tags that are used for inline data from attributes. For example, {"text": "content of attribute: {attribute}"} is processed to {"text": "content of attribute: some data"} if attribute is set to “some data”. Also, there are special tags that map to human records: nm:firstName, nm:lastName, nm:email, nm:phone.

There are set of predefined intents that can be used as starting intent, intent to show the menu and intent to get the help information accordingly: nm:start, nm::menu, nm:help.

Humans can break out, cancel or start the current conversation over at any time. There are special intents that reflect this kind of situations: nm:breakOut, nm:cancel and nm:startOver. Usually these intents are used internally by dialog actions, which allow to mark logical start and end points of the dialog inside the conversation and control its execution.

In order to do not extract intents from some text samples they can be listed as expressions for nm:text intent.

Intents recognition can be controlled by using contexts. Context is specified by context property of interaction and context value is automatically assigned to nm:context attribute when interaction is started. Because nm:context is an attribute it can be manually set or reset at any time by using updateAttribute action. Training expressions can use excludeContext property to indicate that they must not be taken into account when intent recognition will be done within specified context.

nm:payload attribute can be used to access payload of current inbound message. If current inbound message doesn’t have payload or its payload is empty then nm:payload is set to null. Payload can be set for postback buttons and text quick replies to provide information for further processing of human actions.

Bot Properties

A list of various object and properties used when working with a Bot.

Bot Object Properties

Parameter Description
id The id of the Bot.
name The name of the Bot. Used for references.
interactions An array of Interaction Objects.
dateCreated The date and time the Bot was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
currentRevision The current revision number of the bot.
latestRevision The latest revision number of the bot.

Interaction Object Properties

Parameter Description
name The name of the interaction. Used for references. (Optional)
include The name of interaction that will be included as part of the current interaction. Can be a string or an array of strings. (Optional)
intents The intents of the interaction. It can be an array containing strings and/or Intent Objects inside. The interaction will be executed if any of these intents match human’s intent. (Optional)
context Automatically sets nm:context attribute to the specified value when human enters the interaction. If it is absent or null then nm:context attribute is removed. (Optional)
keywords The keywords of the bot. It’s an array of Keyword Objects. (Optional)
expressions The expressions of the bot. It’s an array of Expression Objects. (Optional)
actions An array of Action Objects.
validation A Validation Object that is called before execution of the interaction.

Keyword Object Properties

Parameter Description
name The name of the keyword. (Required)
values An array of Keyword Values with training data for this keyword. (Required)

Keyword Value Object Properties

Parameter Description
value The keyword’s value. (Required)
expressions An array of strings that will be recognized as this keyword value. (Required)

Expression Object Properties

Parameter Description
text The text of the expression. (Required)
generate Specifies whether the expression’s content should be generated based on keyword values of slots or not. It allows to reduce the amount of samples if expression uses one or many slots with keywords. (Optional, default to **true)
slots An array of Slots with mapping of values for this expression. (Required)

Expression Slot Object Properties

Parameter Description
name The name of the slot. (Required)
type The type of the slot. In order to reference a bot keyword by name the type should be prefixed with keyword:. (Required)
value The value of the slot sample in the expression’s text. (Required)

Intent Object Properties

Parameter Description
name The name of the intent. (Optional)
excludeContext Allows to skip the intent if specified value matches the current context stored in nm:context attribute. (Optional)
expressions An array of expressions with training data for this intent. Each expression can be a simple string or Expression Object (Required)

Action Object Properties

Parameter Description
name The name of action. Used for references. (Optional)
conditions An array of Condition Objects for this action. (Optional)
send A Send Action Object.
updateAttribute A Update Attribute Action Object.
waitFor An Wait Action Object.
startDialog A Start Dialog Action Object.
finishDialog Action that finishes the dialog started by startDialog action. Must be set to true.
assignTags A Tag name or an array of Tag names. The action will assign specified tag(s) to a human.
subscribe A boolean value. When set to true the action will subscribe a human to a channel. When set to false the action will unsubscribe a human from a channel.
execute The names of the interactions/actions that will be executed as part of this action. (Optional)
goto Stops current chain of actions execution and continue execution starting from the specified interaction/action. (Optional)
pause A Pause Object that allows to slow down the execution.
validation A Validation Object that is called after execution of the action.

send, waitFor, startDialog, finishDialog, assignTags, subscribe, execute, goto and pause properties are mutually exclusive.

Send Action Object Properties

Parameter Description
message A Message Object with the contents of the message. Tags can be used for text messages.
email A Email Object with the data to send an email. Tags can be used for email data.
request A Request Object with the data to send a request. Tags can be used for request address and data.
note A Note Object with the contents of the note.
rss A RSS Message Object.
json Allows to send any custom JSON in channels that support it. Tags can be used inside string values of JSON.

message, note and rss properties are mutually exclusive.

Update Attribute Action Object Properties

Parameter Description
attribute Name of the attribute where value will be saved. (Required)
value Value of the attribute. Tags can be used for content of this property. If it is null then attribute will be removed. (Required)
evaluate Specifies whether the value’s content should be evaluated or not. Evaluation is done after tags processing. (Optional, default to **false)

Wait Action Object Properties

Parameter Description
data Type of the expected data. Can be message, quick reply, file or an array with these values. (Required)
content Attribute name where received data will be stored when awaited event occurs. Tags can be used for content. (Required)
keywords An array of keyword data mapping that can be used to store multiple attributes at once. Each item contains name property with name of the keyword and attribute property with name of the attribute. (Optional)
executeOnError The array with names of the interactions/actions that will be executed if data is not valid when content is set to one of nm:firstName, nm:lastName, nm:email or nm:phone. (Optional)

Start Dialog Action Object Properties

Parameter Description
breakOut An object with configuration for nm:breakOut intent. Can contain execute property with names of interactions/actions that will be executed when the human breaks out the conversation. (Optional)
cancel An object with configuration for nm:cancel intent. Can contain execute property with names of interactions/actions that will be executed when the human cancels the conversation. (Optional)
startOver An object with configuration for nm:startOver intent. Can contain execute property names of interactions/actions that will be executed when the human starts the conversation over. (Optional)

Email Object Properties

Parameter Description
to A non-empty array with email addresses of the recipients. Tags can be used. (Required)
cc An array with email addresses of the carbon copy recipients. Tags can be used. (Optional)
bcc An array with email addresses of the blind carbon copy recipients. Tags can be used. (Optional)
subject The subject of the email. Tags can be used. (Optional)
text The text of the email. Tags can be used. (Required)
isHtml Indicates whether the email’s content is HTML or not. (Optional, default to **false)

Request Object Properties

Parameter Description
async Specifies whether the request should be processed asynchronously or synchronously. (Optional, default to **true)
method The HTTP method of the request. Can be one of OPTIONS, GET, HEAD, POST, PUT, PATCH, DELETE and TRACE. (Optional, default to **GET)
url The URL where this request will be sent. Tags can be used. (Required)
dataFormat The data format of the request content. Can be either text or json. Can be used only with POST, PUT and PATCH requests. (Optional, default to **text)
content The content of the request. Tags can be used. (Required for **POST, **PUT* and PATCH requests)*
response The data mapping of the response in JSON format in the form {"field": "{value}"}. Fields values are then saved in human attributes. (Optional)
retries The number of retries for this request. (Optional, default to **0)
fallback The name of the interaction/action that will be executed if all attempts to make this requests are failed. (Optional)

Note Object Properties

Parameter Description
text The text of the note. Tags can be used. (Required)
channelId The channel identifier that will be used to send notes. Only Text Us channels are supported right now. (Required)
executeOnError The array with names of the interactions/actions that will be executed if note is not sent. (Optional)

RSS Message Object Properties

Parameter Description
preferedLayout Type of the preferred layout. carousel and list are only supported right now. (Optional) Default is carousel.
url The URL of the RSS feed to be read and sent. (Required)

Pause Object Properties

Parameter Description
seconds Number of seconds for this pause. (Optional) Default is 0.
milliseconds Number of milliseconds for this pause. (Optional) Default is 0.

Seconds and milliseconds can be used together, but the total time of the pause must not be greater than 5 seconds.

Condition Object Properties

Parameter Description
channelTypes An array of Channel Types for which this action is suitable.
comparisons An array of Comparison Arrays for this condition. (Required)
unit Unit name that can be specified to compare distances. Values are: centimetre, inch, foot, yard, metre, kilometre, mile. (Optional). Default is metre.
precision Variation of error in data that is acceptable for comparison. (Optional). Default is 0.

Comparison Array Properties

Parameter Description
0 The attribute name with the left hand side value of this comparison. (Required)
1 The comparison operator. Can be one of “<” (or “less”), “<=” (or “less or equal”), “=” (or “==”, “equal”), “<>” (or “!=”, “not equal”), “>=” (or “greater or equal”), “>” (or “greater”) or is (with right hand side values present or absent to check whether attribute contains any value or not). (Required)
2 The right hand side value of this comparison. (Required)

Validation Object Properties

Parameter Description
content The attribute name where data for this validation is stored. (Required)
pattern The string containing regular expression that should be passed to consider the content as valid. (Required)
executeOnError The array with names of the interactions/actions that will be executed if data is not valid. (Required)

Get a List of Bots

List Bots Request:

curl "https://api.nativemsg.com/v1/bots"
  -H "Authorization: Bearer <API_TOKEN>"

curl "https://api.nativemsg.com/v1/bots?with_flows=true"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/bots");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/bots", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/bots");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/bots");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/bots',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

List Bots Response:

200 OK

[
  {
    "id": 10,
    "name": "example interaction",
    "currentRevision": 1,
    "latestRevision": 1,
    "interactions": [
      {
        "intents": [
          "send response"
        ],
        "actions": [
          {
            "send": {
              "message": {
                "text": "example response"
              }
            }
          }
        ]
      },
      {
        "intents": [
          "enter text"
        ],
        "actions": [
          {
            "send": {
              "message": {
                "text": "please enter some text"
              }
            }
          },
          {
            "waitFor": {
              "data": "message",
              "content": "someText"
            }
          },
          {
            "send": {
              "message": {
                "text": "thank you for entering {someText}"
              }
            }
          }
        ]
      }
    ],
    "dateCreated": "2017-02-25T18:00:00"
  }
]

The endpoint will return an array of bots.

HTTP GET Request

GET https://api.nativemsg.com/v1/bots

Get Bots Properties

Parameter Description
with_flows (true or false) If true, lists the connected bots only, sorted by name. (Optional)

Get Bots List Response

Parameter Description
id The id of the bot
name The name of the bot (100 characters max)
interactions An array of the Interaction Objects.
dateCreated The date and time the bot was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
currentRevision The current revision number of the bot.
latestRevision The latest revision number of the bot.

Get a Bot

Bot Request:

curl "https://api.nativemsg.com/v1/bots/10"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/bots/10");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/bots/10", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/bots/10");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/bots/10");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/bots/10',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Bot Response:

200 OK

{
  "id": 10,
  "name": "example interaction",
  "currentRevision": 1,
  "latestRevision": 1,
  "interactions": [
    {
      "intents": [
        "send response"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "example response"
            }
          }
        }
      ]
    },
    {
      "intents": [
        "enter text"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "please enter some text"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "someText"
          }
        },
        {
          "send": {
            "message": {
              "text": "thank you for entering {someText}"
            }
          }
        }
      ]
    }
  ],
  "dateCreated": "2017-02-25T18:00:00"
}

The endpoint will get a single Bot by id.

HTTP GET Request

GET https://api.nativemsg.com/v1/bots/{bot_id}

Get Bot Response

Parameter Description
id The id of the bot
name The name of the bot (100 characters max)
interactions An array of the Interaction Objects.
dateCreated The date and time the bot was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
currentRevision The current revision number of the bot.
latestRevision The latest revision number of the bot.

Add a Bot

Add Bot Request:

curl "https://api.nativemsg.com/v1/bots"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"name\":\"example interaction\",
      \"interactions\":[{
        \"intents\":[\"send response\"],
        \"actions\":[{
          \"send\": {
            \"message\": {
              \"text\":\"example response\"
            }
          }
        }]
      },{
        \"intents\":[\"enter text\"],
        \"actions\":[{
          \"send\": {
            \"message\": {
              \"text\":\"please enter some text\"
            }
          }
        },{
          \"waitFor\":{
            \"data\":\"message\",
            \"content\":\"someText\"
          }
        },{
          \"send\": {
            \"message\": {
              \"text\": \"thank you for entering {someText}\"
            }
          }
        }
      ]
    }
  ]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/bots");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"name\": \"example interaction\"," +
            "\"interactions\": [" +
                "{" +
                    "\"intents\": [" +
                        "\"send response\"" +
                    "]," +
                    "\"actions\": [" +
                        "{" +
                            "\"send\": {" +
                                "\"message\": {" +
                                    "\"text\": \"example response\"" +
                                "}" +
                            "}" +
                        "}" +
                    "]" +
                "}," +
                "{" +
                    "\"intents\": [" +
                        "\"enter text\"" +
                    "]," +
                    "\"actions\": [" +
                        "{" +
                            "\"send\": {" +
                                "\"message\": {" +
                                    "\"text\": \"please enter some text\"" +
                                "}" +
                            "}" +
                        "}," +
                        "{" +
                            "\"waitFor\": {" +
                                "\"data\": \"message\"," +
                                "\"content\": \"someText\"" +
                            "}" +
                        "}," +
                        "{" +
                            "\"send\": {" +
                                "\"message\": {" +
                                    "\"text\": \"thank you for entering {someText}\"" +
                                "}" +
                            "}" +
                        "}" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "name": "example interaction",
    "interactions": [
        {
            "intents": [
                "send response"
            ],
            "actions": [
                {
                    "send": {
                        "message": {
                            "text": "example response"
                        }
                    }
                }
            ]
        },
        {
            "intents": [
                "enter text"
            ],
            "actions": [
                {
                    "send": {
                        "message": {
                            "text": "please enter some text"
                        }
                    }
                },
                {
                    "waitFor": {
                        "data": "message",
                        "content": "someText"
                    }
                },
                {
                    "send": {
                        "message": {
                            "text": "thank you for entering {someText}"
                        }
                    }
                }
            ]
        }
    ]
}"""
connection.request("POST", "/v1/bots", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""name"": ""example interaction"",
            ""interactions"": [
                {
                    ""intents"": [
                        ""send response""
                    ],
                    ""actions"": [
                        {
                            ""send"": {
                                ""message"": {
                                    ""text"": ""example response""
                                }
                            }
                        }
                    ]
                },
                {
                    ""intents"": [
                        ""enter text""
                    ],
                    ""actions"": [
                        {
                            ""send"": {
                                ""message"": {
                                    ""text"": ""please enter some text""
                                }
                            }
                        },
                        {
                            ""waitFor"": {
                                ""data"": ""message"",
                                ""content"": ""someText""
                            }
                        },
                        {
                            ""send"": {
                                ""message"": {
                                    ""text"": ""thank you for entering {someText}""
                                }
                            }
                        }
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/bots", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/bots");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'example interaction',
    'interactions' => [
        {
            'intents' => [
                'send response'
            ],
            'actions' => [
                {
                    'send' => {
                        'message' => {
                            'text' => 'example response'
                        ]
                    }
                }
            ]
        },
        {
            'intents' => [
                'enter text'
            ],
            'actions' => [
                {
                    'send' => {
                        'message' => {
                            'text' => 'please enter some text'
                        }
                    }
                },
                {
                    'waitFor' => {
                        'data' => 'message',
                        'content' => 'someText'
                    }
                },
                {
                    'send' => {
                        'message' => {
                            'text' => 'thank you for entering {someText}'
                        }
                    }
                }
            ]
        }
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/bots',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    name: 'example interaction',
    interactions: [
        {
            intents: [
                'send response'
            ],
            actions: [
                {
                    send: {
                        message: {
                            text: 'example response'
                        }
                    }
                }
            ]
        },
        {
            intents: [
                'enter text'
            ],
            actions: [
                {
                    send: {
                        message: {
                            text: 'please enter some text'
                        }
                    }
                },
                {
                    waitFor: {
                        data: 'message',
                        content: 'someText'
                    }
                },
                {
                    send: {
                        message: {
                            text: 'thank you for entering {someText}'
                        }
                    }
                }
            ]
        }
    ]
}));
request.end();

Add Bot Response:

200 OK

{
  "id": 100,
  "name": "example bot",
  "currentRevision": 1,
  "latestRevision": 1,
  "interactions": [
    {
      "intents": [
        "send response"
      ],
      "actions": [
        {
          "send.message.text": "example response"
        }
      ]
    },
    {
      "intents": [
        "enter text"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "please enter some text"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "someText"
          }
        },
        {
          "send": {
            "message": {
              "text": "thank you for entering {someText}"
            }
          }
        }
      ]
    }
  ],
  "dateCreated": "2017-02-28T18:00:00"
}

This endpoint will add a new Bot.

HTTP POST Request

POST https://api.nativemsg.com/v1/bots

POST JSON Payload

Parameter Description
name The name of the bot (100 characters max). Required.
interactions An array of the Interaction Objects. Required.

The successful creation of a new Bot will return the Bot object below.

POST Bot Response

Parameter Description
id The id of the bot
name The name of the bot (100 characters max)
interactions An array of the Interaction Objects.
dateCreated The date and time the bot was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
currentRevision The current revision number of the bot.
latestRevision The latest revision number of the bot.

Update a Bot

Update Bot Request:

curl "https://api.nativemsg.com/v1/bots/100"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X PUT

  -d "{\"name\":\"updated example bot\",
      \"interactions\":[{
        \"intents\":[\"send response\"],
        \"actions\":[{
          \"send\":{
            \"message\": {
              \"text\":\"example response\"
            }
          }
        }]
      },{
        \"intents\":[\"enter text\"],
        \"actions\":[{
          \"send\": {
            \"message\": {
              \"text\":\"please enter some text\"
            }
          }
        },{
          \"waitFor\":{
            \"data\":\"message\",
            \"content\":\"someText\"
          }
        },{
          \"send\": {
            \"message\": {
              \"text\": \"thank you for entering {someText}\"
            }
          }
        }
      ]
    }
  ]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPut request = new HttpPut("https://api.nativemsg.com/v1/bots/100");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"name\": \"updated example bot\"," +
            "\"interactions\": [" +
                "{" +
                    "\"intents\": [" +
                        "\"send response\"" +
                    "]," +
                    "\"actions\": [" +
                        "{" +
                            "\"send\": {" +
                                "\"message\": {" +
                                    "\"text\": \"example response\"" +
                                "}" +
                            "}" +
                        "}" +
                    "]" +
                "}," +
                "{" +
                    "\"intents\": [" +
                        "\"enter text\"" +
                    "]," +
                    "\"actions\": [" +
                        "{" +
                            "\"send\": {" +
                                "\"message\": {" +
                                    "\"text\": \"please enter some text\"" +
                                "}" +
                            "}" +
                        "}," +
                        "{" +
                            "\"waitFor\": {" +
                                "\"data\": \"message\"," +
                                "\"content\": \"someText\"" +
                            "}" +
                        "}," +
                        "{" +
                            "\"send\": {" +
                                "\"message\": {" +
                                    "\"text\": \"thank you for entering {someText}\"" +
                                "}" +
                            "}" +
                        "}" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "name": "updated example bot",
    "interactions": [
        {
            "intents": [
                "send response"
            ],
            "actions": [
                {
                    "send": {
                        "message": {
                            "text": "example response"
                        }
                    }
                }
            ]
        },
        {
            "intents": [
                "enter text"
            ],
            "actions": [
                {
                    "send": {
                        "message": {
                            "text": "please enter some text"
                        }
                    }
                },
                {
                    "waitFor": {
                        "data": "message",
                        "content": "someText"
                    }
                },
                {
                    "send": {
                        "message": {
                            "text": "thank you for entering {someText}"
                        }
                    }
                }
            ]
        }
    ]
}"""
connection.request("PUT", "/v1/bots/100", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""name"": ""updated example bot"",
            ""interactions"": [
                {
                    ""intents"": [
                        ""send response""
                    ],
                    ""actions"": [
                        {
                            ""send"": {
                                ""message"": {
                                    ""text"": ""example response""
                                }
                            }
                        }
                    ]
                },
                {
                    ""intents"": [
                        ""enter text""
                    ],
                    ""actions"": [
                        {
                            ""send"": {
                                ""message"": {
                                    ""text"": ""please enter some text""
                                }
                            }
                        },
                        {
                            ""waitFor"": {
                                ""data"": ""message"",
                                ""content"": ""someText""
                            }
                        },
                        {
                            ""send"": {
                                ""message"": {
                                    ""text"": ""thank you for entering {someText}""
                                }
                            }
                        }
                    ]
                }
            ]
        }";

    var response = await client.PutAsync("https://api.nativemsg.com/v1/bots/100", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/bots/100");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'updated example bot',
    'interactions' => [
        {
            'intents' => [
                'send response'
            ],
            'actions' => [
                {
                    'send' => {
                        'message' => {
                            'text' => 'example response'
                        ]
                    }
                }
            ]
        },
        {
            'intents' => [
                'enter text'
            ],
            'actions' => [
                {
                    'send' => {
                        'message' => {
                            'text' => 'please enter some text'
                        }
                    }
                },
                {
                    'waitFor' => {
                        'data' => 'message',
                        'content' => 'someText'
                    }
                },
                {
                    'send' => {
                        'message' => {
                            'text' => 'thank you for entering {someText}'
                        }
                    }
                }
            ]
        }
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/bots/100',
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    name: 'updated example bot',
    interactions: [
        {
            intents: [
                'send response'
            ],
            actions: [
                {
                    send: {
                        message: {
                            text: 'example response'
                        }
                    }
                }
            ]
        },
        {
            intents: [
                'enter text'
            ],
            actions: [
                {
                    send: {
                        message: {
                            text: 'please enter some text'
                        }
                    }
                },
                {
                    waitFor: {
                        data: 'message',
                        content: 'someText'
                    }
                },
                {
                    send: {
                        message: {
                            text: 'thank you for entering {someText}'
                        }
                    }
                }
            ]
        }
    ]
}));
request.end();

Update Bot Response:

200 OK

{
  "id": 100,
  "name": "updated example bot",
  "interactions": [
    {
      "intents": [
        "send response"
      ],
      "actions": [
        {
          "send.message.text": "example response"
        }
      ]
    },
    {
      "intents": [
        "enter text"
      ],
      "actions": [
        {
          "send.message.text": "please enter some text"
        },
        {
          "waitFor": {
            "data": "message",
            "content": "someText"
          }
        },
        {
          "send.message.text": "thank you for entering {someText}"
        }
      ]
    }
  ],
  "dateCreated": "2017-02-28T18:00:00"
}

This endpoint will update an existing Bot.

HTTP PUT Request

PUT https://api.nativemsg.com/v1/bots/{bot_id}

PUT JSON Payload

Parameter Description
name The name of the bot (100 characters max)
interactions An array of the Interaction Objects.

The successful update of a Bot will return the updated Bot object below.

PUT Bot Response

Parameter Description
id The id of the bot
name The name of the bot (100 characters max)
interactions An array of the Interaction Objects.
dateCreated The date and time the bot was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Delete a Bot

Delete Bot Request:

curl "https://api.nativemsg.com/v1/bots/122"
  -H "Authorization: Bearer <API_TOKEN>"
  -X DELETE
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpDelete request = new HttpDelete("https://api.nativemsg.com/v1/bots/122");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("DELETE", "/v1/bots/122", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.DeleteAsync("https://api.nativemsg.com/v1/bots/122");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/bots/122");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/bots/122',
    method: 'DELETE',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Delete Bot Response:

200 OK

{}

This endpoint will delete an existing Bot.

HTTP DELETE Request

DELETE https://api.nativemsg.com/v1/bots/{bot_id}

DELETE Bot Response

A successful deletion will return an HTTP 200 OK response.

Get a List of Bot Revisions

List Bot Revisions Request:

curl "https://api.nativemsg.com/v1/bots/129/revisions"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/bots/129/revisions");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/bots/129/revisions", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/bots/129/revisions");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/bots/129/revisions");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/bots/129/revisions',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

List Bot Revisions Response:

200 OK

[{
  "id": 13,
  "botId": 129,
  "revision": 1,
  "name": "awesome bot",
  "data": "[{\"name\":\"interaction #1\"}]"
}, {
  "id": 14,
  "botId": 129,
  "revision": 2,
  "name": "awesome bot",
  "data": "[{\"name\":\"interaction #2\"}]"
}, {
  "id": 15,
  "botId": 129,
  "revision": 3,
  "name": "awesome bot",
  "data": "[{\"name\":\"interaction #3\"}]"
}]

The endpoint will return an array of bot revisions.

HTTP GET Request

GET https://api.nativemsg.com/v1/bots/{bot_id}/revisions

Get Bot Revisions List Response

Parameter Description
id The id of the bot revision.
botId The bot id.
revision Revision number.
name The name of the bot (100 characters max).
data An array of the Interaction Objects.

Get a Bot Revision

Bot Revision Request:

curl "https://api.nativemsg.com/v1/bots/129/revisions/100"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/bots/129/revisions/100");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/bots/129/revisions/100", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/bots/129/revisions/100");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/bots/129/revisions/100");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/bots/129/revisions/100',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Bot Revision Response:

200 OK

{
  "id": 14,
  "botId": 129,
  "revision": 100,
  "name": "awesome bot",
  "data": "[{\"name\":\"interaction modification #100\"}]"
}

The endpoint will get a single Bot Revision by revision number.

HTTP GET Request

GET https://api.nativemsg.com/v1/bot/{bot_id}/revisions/{revision}

Get Bot Response

Parameter Description
id The id of revision
botId Id for the bot
revision Revision number
name The name of the bot (100 characters max)
data An array of the Interaction Objects.

Restore a Bot Revision

Restore a Bot Revision Request:

curl "https://api.nativemsg.com/v1/bots/129/revisions"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X PUT

  -d "{\"restore\":2}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPut request = new HttpPut("https://api.nativemsg.com/v1/bots/129/revisions");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"restore\": 2" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "restore": 2
}"""
connection.request("PUT", "/v1/bots/129/revisions", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""restore"": 2
        }";

    var response = await client.PutAsync("https://api.nativemsg.com/v1/bots/129/revisions", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/bots/129/revisions");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'restore' => 2
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/bots/129/revisions',
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    restore: 2
}));
request.end();

Restore Bot Revision Response:

200 OK

{
  "restored": true
}

This endpoint will restore a bot revision by revision number.

HTTP PUT Request

PUT https://api.nativemsg.com/v1/bots/{bot_id}/revisions

PUT JSON Payload

Parameter Description
restore Revision number or “latest” string.

The successful restoration of a Bot Revision will return the object below.

PUT Bot Revision Response

Parameter Description
restored true if bot was successfully restored.

Bot Examples

Asks for a Valid Name

Asks for a Valid Name

{
  "name": "example bot",
  "interactions": [
    {
      "intents": [
        "ask for a valid name"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "What is your first name?"
            }
          }
        },
        {
          "name": "wait for the first name",
          "waitFor": {
            "data": "message",
            "content": "nm:firstName",
            "executeOnError": [
              "first name input error",
              "wait for the first name"
            ]
          }
        },
        {
          "send": {
            "message": {
              "text": "Your first name is remembered as {nm:firstName}."
            }
          }
        }
      ]
    },
    {
      "name": "first name input error",
      "actions": [
        {
          "send": {
            "message": {
              "text": "Entered text is not a valid first name. Please enter your first name again."
            }
          }
        }
      ]
    }
  ]
}

Asks for an Email Address

Asks for an Email Address

{
  "name": "example bot",
  "interactions": [
    {
      "intents": [
        "ask for an email address"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "What is your email address?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "nm:email"
          }
        },
        {
          "send": {
            "message": {
              "text": "Thank you for entering your email address. It's remembered as {nm:email}."
            }
          }
        }
      ]
    }
  ]
}

Asks for Basic Information and Controls the Dialog

Asks for Basic Information and Controls the Dialog

{
  "name": "example bot",
  "interactions": [
    {
      "intents": [
        "ask for basic information"
      ],
      "actions": [
        {
          "startDialog": {
            "breakOut": {
              "execute": "break out"
            },
            "cancel": {
              "execute": "cancel",
              "rollback": true
            },
            "startOver": {
              "execute": "start over",
              "rollback": true
            }
          }
        },
        {
          "send": {
            "message": {
              "text": "What is your first name?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "nm:firstName"
          }
        },
        {
          "send": {
            "message": {
              "text": "What is your last name?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "nm:lastName"
          }
        },
        {
          "send": {
            "message": {
              "text": "What is your phone number?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "nm:phone"
          }
        },
        {
          "send": {
            "message": {
              "text": "Thank you, {nm:firstName} {nm:lastName}. Your phone number: {nm:phone}."
            }
          }
        },
        {
          "finishDialog": true
        }
      ]
    },
    {
      "name": "break out",
      "actions": [
        {
          "send": {
            "message": {
              "text": "You stopped this conversation"
            }
          }
        }
      ]
    },
    {
      "name": "cancel",
      "actions": [
        {
          "send": {
            "message": {
              "text": "You cancelled this conversation"
            }
          }
        }
      ]
    },
    {
      "name": "start over",
      "actions": [
        {
          "send": {
            "message": {
              "text": "You started over this conversation"
            }
          }
        }
      ]
    }
  ]
}

Emails Entered Data to a Recipient

Emails Entered Data to a Recipient

{
  "name": "example bot",
  "interactions": [
    {
      "intents": [
        "send email",
        "send an email"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "What is the recipient's email address?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "recipient"
          }
        },
        {
          "send": {
            "message": {
              "text": "What is the content if the email?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "content"
          }
        },
        {
          "send.email": {
            "to": [
              "{recipient}"
            ],
            "cc": [
              "{recipient}"
            ],
            "bcc": [
              "{recipient}"
            ],
            "subject": "This email was sent by the nativeMsg bot",
            "text": "{content}",
            "isHtml": true
          }
        },
        {
          "send": {
            "message": {
              "text": "Your email was sent."
            }
          }
        }
      ]
    }
  ]
}

Sends HTTP Request with Entered Data

Sends HTTP Request with Entered Data

{
  "name": "example bot",
  "interactions": [
    {
      "intents": [
        "send request",
        "send a request"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "What is the recipient's URL?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "recipient"
          }
        },
        {
          "send": {
            "message": {
              "text": "What is the content?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "content"
          }
        },
        {
          "send.request": {
            "method": "POST",
            "url": "{recipient}",
            "dataFormat": "json",
            "content": "{\"data\": \"{content}\"}",
            "retries": 2,
            "fallback": "send email"
          }
        },
        {
          "send": {
            "message": {
              "text": "Your request was sent."
            }
          }
        }
      ]
    },
    {
      "name": "send email",
      "actions": [
        {
          "send": {
            "message": {
              "text": "Your can send fallback email here."
            }
          }
        }
      ]
    }
  ]
}

Sends HTTP Request and Saves Response to Human Attributes

Sends HTTP Request and Saves Response to Human Attributes

{
  "name": "example bot with response mapping",
  "interactions": [
    {
      "intents": [
        "send request"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "What is the request URL?"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "url"
          }
        },
        {
          "send": {
            "request": {
              "method": "GET",
              "url": "{url}",
              "async": false,
              "response": "{\"field\": \"{value}\"}",
              "fallback": "send fallback message"
            }
          }
        },
        {
          "send": {
            "message": {
              "text": "Field value is {value}"
            }
          }
        }
      ]
    },
    {
      "name": "send fallback message",
      "actions": [
        {
          "send": {
            "message": {
              "text": "Failed to send request to {url}."
            }
          }
        }
      ]
    }
  ]
}

Custom Validation for Entered Data

Custom Validation for Entered Data

{
  "name": "example bot",
  "interactions": [
    {
      "intents": [
        "validate uppercase word"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "Please enter any word in uppercase"
            }
          }
        },
        {
          "name": "wait for word",
          "waitFor": {
            "data": "message",
            "content": "word"
          },
          "validation": {
            "content": "word",
            "pattern": "^[A-Z]+$",
            "executeOnError": "validation error"
          }
        }
      ]
    },
    {
      "name": "validation error",
      "actions": [
        {
          "send": {
            "message": {
              "text": "Your entered word in not in uppercase."
            }
          }
        }
      ]
    }
  ]
}

Different Welcome Messages for Facebook and Twitter channels

Different Welcome Messages for Facebook and Twitter channels

{
  "name": "example bot",
  "interactions": [
    {
      "name": "welcome",
      "intents": [
        "nm:start"
      ],
      "actions": [
        {
          "conditions": [
            {
              "channelTypes": [
                "fb"
              ]
            }
          ],
          "send": {
            "message": {
              "text": "Hello, Facebook user!",
              "buttons": [
                {
                  "type": "postback",
                  "title": "Hello, bot!",
                  "payload": "hello"
                }
              ]
            }
          }
        },
        {
          "conditions": [
            {
              "channelTypes": [
                "twr"
              ]
            }
          ],
          "send": {
            "message": {
              "text": "Hello, Twitter user!",
              "quickReplies": [
                {
                  "type": "text",
                  "title": "Hello, bot!",
                  "payload": "hello"
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Channel Subscription for a Human

Channel Subscription for a Human

[
  {
    "intents": [
      "trigger subscribe"
    ],
    "actions": [
      {
        "description": "Channel subscription for a human",
        "send": {
          "message": {
            "text": "Subscribe menu",
            "buttons": [
              {
                "type": "postback",
                "title": "Subscribe",
                "execute": "subscribe"
              },
              {
                "type": "postback",
                "title": "Unsubscribe",
                "execute": "unsubscribe"
              }
            ]
          }
        }
      }
    ]
  },
  {
    "name": "subscribe",
    "actions": [
      {
        "subscribe": true
      },
      {
        "send": {
          "message": {
            "text": "You were subscribed to a channel."
          }
        }
      }
    ]
  },
  {
    "name": "unsubscribe",
    "actions": [
      {
        "subscribe": false
      },
      {
        "send": {
          "message": {
            "text": "You were unsubscribed from a channel."
          }
        }
      }
    ]
  }
]

Assign Tags to a Human

Assign Tags to a Human

[
  {
    "intents": [
      "trigger assignTags"
    ],
    "actions": [
      {
        "description": "Assign tags to a human",
        "send": {
          "message": {
            "text": "Assign tags",
            "buttons": [
              {
                "type": "postback",
                "title": "tag1",
                "execute": "tag1"
              },
              {
                "type": "postback",
                "title": "tag2 and tag3",
                "execute": "tag23"
              }
            ]
          }
        }
      }
    ]
  },
  {
    "name": "tag1",
    "actions": [
      {
        "assignTags": "tag1"
      },
      {
        "send": {
          "message": {
            "text": "You were assigned to the tag `tag1`."
          }
        }
      }
    ]
  },
  {
    "name": "tag23",
    "actions": [
      {
        "assignTags": [
          "tag2",
          "tag3"
        ]
      },
      {
        "send": {
          "message": {
            "text": "You were assigned to tags `tag2` and `tag3`."
          }
        }
      }
    ]
  }
]

Conversation based on context

Conversation based on context

{
  "name": "conversation based on context",
  "interactions": [
    {
      "intents": [
        {
          "expressions": [
            {
              "text": "input without context"
            }
          ]
        }
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "Type 'first' or 'second' word"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "input"
          }
        },
        {
          "send": {
            "message": {
              "text": "You typed: {input}"
            }
          }
        }
      ]
    },
    {
      "context": "awaiting text instead of intent",
      "intents": [
        {
          "expressions": [
            {
              "text": "input with context"
            }
          ]
        }
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "Type 'first' or 'second' word"
            }
          }
        },
        {
          "waitFor": {
            "data": "message",
            "content": "input"
          }
        },
        {
          "send": {
            "message": {
              "text": "You typed: {input}"
            }
          }
        }
      ]
    },
    {
      "intents": [
        {
          "expressions": [
            {
              "text": "first"
            }
          ]
        }
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "message #1"
            }
          }
        }
      ]
    },
    {
      "intents": [
        {
          "excludeContext": "awaiting text instead of intent",
          "expressions": [
            {
              "text": "second"
            }
          ]
        }
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "message #2"
            }
          }
        }
      ]
    }
  ]
}

Humans

A Human is a living breathing person. A Human interacts with nativeMsg via one of the various messaging platforms - Facebook, Slack, SMS, MMS, etc.

Get a List of Humans

List Humans Request:

curl "https://api.nativemsg.com/v1/humans"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/humans");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/humans", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/humans");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

List Humans Response:

200 OK

[
  {
    "id": 771,
    "name": "Chris Chiovare",
    "firstName": "Chris",
    "lastName": "Chiovare",
    "gender": "M",
    "timezone": 3.0,
    "dateCreated": "2017-11-29T11:02:15",
    "profilePic": "https://example.com/pictureOfMe.jpg",
    "locale": "en_US",
    "channelIds": [
      569
    ],
    "customFields": {
      "page": "10",
      "option": "2",
      "custom": "value"
    },
    "connectedChannelTypes": [
      "fb",
      "twr",
      "tus",
      "alx",
      "web"
    ],
    "botEnabled": true
  },
]

The endpoint will return an array of Humans associated to your account.

HTTP GET Request

GET https://api.nativemsg.com/v1/humans

Get Humans List Response

Parameter Description
id The id of the Human
name The name of the Human. This could be a username or first name + last name depending on the channel.
firstName The first name of the Human.
lastName The last name of the Human.
gender M or F
timezone The integer value +/- from GMT 0.
locale The locale of the user. Example en_US.
profilePic URL of the profile picture if one is available.
dateCreated The date and time the Human was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
channelIds The list of channel ids the human belongs to.
connectedChannelTypes The list of channel types of the human’s flow.
customFields Object with all custom fields that are set during the conversation.
botEnabled Indicates whether a flow’s bot is enabled for this human or not.

Get a Human

Human Request:

curl "https://api.nativemsg.com/v1/humans/8767"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/humans/8767");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/humans/8767", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/humans/8767");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/8767");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/8767',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Human Response:

200 OK

{
  "id": 771,
  "name": "Chris Chiovare",
  "firstName": "Chris",
  "lastName": "Chiovare",
  "gender": "M",
  "timezone": 3.0,
  "dateCreated": "2017-11-29T11:02:15",
  "profilePic": "https://example.com/pictureOfMe.jpg",
  "locale": "en_US",
  "channelIds": [
    569
  ],
  "customFields": {
    "page": "10",
    "option": "2",
    "custom": "value"
  },
  "connectedChannelTypes": [
    "fb",
    "twr",
    "tus",
    "alx",
    "web"
  ],
  "botEnabled": true
}

The endpoint will get a single Human by id.

HTTP GET Request

GET https://api.nativemsg.com/v1/humans/{human_id}

Get Human Response

Parameter Description
id The id of the Human
name The name of the Human. This could be a username or first name + last name depending on the channel.
firstName The first name of the Human.
lastName The last name of the Human.
gender M or F
timezone The integer value +/- from GMT 0.
locale The locale of the user. Example en_US.
profilePic URL of the profile picture if one is available.
dateCreated The date and time the Human was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
channelIds The list of channel ids the human belongs to.
connectedChannelTypes The list of channel types of the human’s flow.
customFields Object with all custom fields that are set during the conversation.
botEnabled Indicates whether a flow’s bot is enabled for this human or not.

Update a Human

Update Human Request:

curl "https://api.nativemsg.com/v1/humans/6837"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X PUT
  -d "{\"botEnabled\":false}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPut request = new HttpPut("https://api.nativemsg.com/v1/humans/6837");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"botEnabled\": false" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "botEnabled": false
}"""
connection.request("PUT", "/v1/humans/6837", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""botEnabled"": false
        }";

    var response = await client.PutAsync("https://api.nativemsg.com/v1/humans/6837", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/6837");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'botEnabled' => false
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/6837',
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    botEnabled: false
}));
request.end();

Update Human Response:

200 OK

{
  "id": 6837,
  "name": "Chris Chiovare",
  "firstName": "Chris",
  "lastName": "Chiovare",
  "gender": "M",
  "timezone": 3.0,
  "dateCreated": "2017-11-29T11:02:15",
  "profilePic": "https://example.com/pictureOfMe.jpg",
  "locale": "en_US",
  "channelIds": [
    569
  ],
  "customFields": {
    "page": "10",
    "option": "2",
    "custom": "value"
  },
  "connectedChannelTypes": [
    "fb",
    "twr",
    "tus",
    "alx",
    "web"
  ],
  "botEnabled": false
}

This endpoint will update an existing human.

HTTP PUT Request

PUT https://api.nativemsg.com/v1/humans/{human_id}

PUT JSON Payload

Parameter Description
botEnabled Indicates whether a flow’s bot is enabled for this human or not.

PUT Human Response

Parameter Description
id The id of the Human
name The name of the Human. This could be a username or first name + last name depending on the channel.
firstName The first name of the Human.
lastName The last name of the Human.
gender M or F
timezone The integer value +/- from GMT 0.
locale The locale of the user. Example en_US.
profilePic URL of the profile picture if one is available.
dateCreated The date and time the Human was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
channelIds The list of channel ids the human belongs to.
connectedChannelTypes The list of channel types of the human’s flow.
customFields Object with all custom fields that are set during the conversation.
botEnabled Indicates whether a flow’s bot is enabled for this human or not.

Get a List of Tags Assigned to a Human

List of Tags Assigned to a Human Request:

curl "https://api.nativemsg.com/v1/humans/542/tags"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/humans/542/tags");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/humans/542/tags", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/humans/542/tags");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/542/tags");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/542/tags',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

List of Tags Assigned to a Human Response:

200 OK

[
  {
    "id": 4,
    "name": "tag0",
    "description": "tag0",
    "dateCreated": "2017-12-27T13:55:14",
    "dateUpdated": "2018-01-16T12:02:16"
  },
]

The endpoint will return an array of Tags assigned to a human.

HTTP GET Request

GET https://api.nativemsg.com/v1/humans/{human_id}/tags

HTTP GET Response

Parameter Description
id The id of the Tag.
name The name of the Tag. Should be unique for user account.
description The description of the Tag.
dateCreated The date and time the Tag was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Assign Tags to a Human

Assign Tags to a Human by Names

Assign Tags to a Human by Names Request:

curl "https://api.nativemsg.com/v1/humans/542/tags/assign"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"tags\":[\"tag1\",\"tag2\",\"tag3\"]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/humans/542/tags/assign");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"tags\": [" +
                "\"tag1\"," +
                "\"tag2\"," +
                "\"tag3\"" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "tags": [
        "tag1",
        "tag2",
        "tag3"
    ]
}"""
connection.request("POST", "/v1/humans/542/tags/assign", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""tags"": [
                ""tag1"",
                ""tag2"",
                ""tag3""
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/humans/542/tags/assign", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/542/tags/assign");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'tags' => [
        'tag1',
        'tag2',
        'tag3'
    ]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/542/tags/assign',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    tags: [
        'tag1',
        'tag2',
        'tag3'
    ]
}));
request.end();

Assign Tags to a Human by Names Response:

200 OK

{
  "code": 200,
  "message": "Tags were successfully assigned to human #542."
}

This endpoint will assign specified tags to a human in your account.

HTTP POST Request

POST https://api.nativemsg.com/v1/humans/{humanId}/tags/assign

POST JSON Payload

Parameter Description
tags An array of tag names.

The successful assignment of tags to a human will return the object below.

HTTP POST Response

Parameter Description
code The HTTP status code returned
message Message about tag assignment result

Assign Tags to a Human by Ids

Assign Tags to a Human by Ids Request:

curl "https://api.nativemsg.com/v1/humans/542/tags/assign"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"tagIds\":[1,2,3]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/humans/542/tags/assign");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"tagIds\": [" +
                "1," +
                "2," +
                "3" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "tagIds": [
        1,
        2,
        3
    ]
}"""
connection.request("POST", "/v1/humans/542/tags/assign", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""tagIds"": [
                1,
                2,
                3
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/humans/542/tags/assign", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/542/tags/assign");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'tagIds' => [
        1,
        2,
        3
    ]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/542/tags/assign',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    tagIds: [
        1,
        2,
        3
    ]
}));
request.end();

Assign Tags to a Human by Ids Response:

200 OK

{
  "code": 200,
  "message": "Tags were successfully assigned to human #542."
}

This endpoint will assign specified tags to a human in your account.

HTTP POST Request

POST https://api.nativemsg.com/v1/humans/{humanId}/tags/assign

POST JSON Payload

Parameter Description
tagIds An array of tag Ids.

The successful assignment of tags to a human will return the object below.

HTTP POST Response

Parameter Description
code The HTTP status code returned
message Message about tag assignment result

Unassign Tags from a Human

Unassign Tags from a Human by Names

Unassign Tags from a Human by Names Request:

curl "https://api.nativemsg.com/v1/humans/542/tags/unassign"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"tags\":[\"tag1\",\"tag2\",\"tag3\"]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/humans/542/tags/unassign");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"tags\": [" +
                "\"tag1\"," +
                "\"tag2\"," +
                "\"tag3\"" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "tags": [
        "tag1",
        "tag2",
        "tag3"
    ]
}"""
connection.request("POST", "/v1/humans/542/tags/unassign", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""tags"": [
                ""tag1"",
                ""tag2"",
                ""tag3""
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/humans/542/tags/unassign", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/542/tags/unassign");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'tags' => [
        'tag1',
        'tag2',
        'tag3'
    ]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/542/tags/unassign',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    tags: [
        'tag1',
        'tag2',
        'tag3'
    ]
}));
request.end();

Unassign Tags from a Human by Names Response:

200 OK

{
  "code": 200,
  "message": "Tags were successfully unassigned from human #542."
}

This endpoint will unassign specified tags from a human in your account.

HTTP POST Request

POST https://api.nativemsg.com/v1/humans/{humanId}/tags/unassign

POST JSON Payload

Parameter Description
tags An array of tag names.

The successful unassignment of tags from a human will return the object below.

HTTP POST Response

Parameter Description
code The HTTP status code returned.
message Message about tag unassignment result.

Unassign Tags from a Human by Ids

Unassign Tags from a Human by Ids Request:

curl "https://api.nativemsg.com/v1/humans/542/tags/unassign"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"tagIds\":[1,2,3]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/humans/542/tags/unassign");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"tagIds\": [" +
                "1," +
                "2," +
                "3" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "tagIds": [
        1,
        2,
        3
    ]
}"""
connection.request("POST", "/v1/humans/542/tags/unassign", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""tagIds"": [
                1,
                2,
                3
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/humans/542/tags/unassign", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/542/tags/unassign");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'tagIds' => [
        1,
        2,
        3
    ]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/542/tags/unassign',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    tagIds: [
        1,
        2,
        3
    ]
}));
request.end();

Unassign Tags from a Human by Ids Response:

200 OK

{
  "code": 200,
  "message": "Tags were successfully unassigned from human #542."
}

This endpoint will unassign specified tags from a human in your account.

HTTP POST Request

POST https://api.nativemsg.com/v1/humans/{humanId}/tags/unassign

POST JSON Payload

Parameter Description
tagIds An array of tag Ids.

The successful unassignment of tags from a human will return the object below.

HTTP POST Response

Parameter Description
code The HTTP status code returned.
message Message about tag unassignment result.

Subscribe a Human to a Channel

Subscribe a Human to a Channel Request:

curl "https://api.nativemsg.com/v1/humans/542/subscription"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/humans/542/subscription");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("POST", "/v1/humans/542/subscription", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.PostAsync("https://api.nativemsg.com/v1/humans/542/subscription", null);
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/542/subscription");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/542/subscription',
    method: 'POST',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Subscribe a Human to a Channel Response:

200 OK

{
    "channnelId": 551,
    "humanId": 542,
    "subscription": true
}

This endpoint will subscribe a human to a channel.

HTTP POST Request

POST https://api.nativemsg.com/v1/humans/<human_id>/subscription

The successful subscription of a human to a channel will return the object below.

POST Tag Response

Parameter Description
channelId The id of the channel.
humanId The id of the human.
subscription The human’s subscription state in the channel.

Unsubscribe a Human from a Channel

Unsubscribe a Human from a Channel Request:

curl "https://api.nativemsg.com/v1/humans/542/subscription"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X DELETE
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpDelete request = new HttpDelete("https://api.nativemsg.com/v1/humans/542/subscription");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("DELETE", "/v1/humans/542/subscription", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.DeleteAsync("https://api.nativemsg.com/v1/humans/542/subscription");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/542/subscription");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/542/subscription',
    method: 'DELETE',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Unsubscribe a Human from a Channel Response:

200 OK

{
    "channnelId": 551,
    "humanId": 542,
    "subscription": false
}

This endpoint will unsubscribe a human from a channel.

HTTP DELETE Request

DELETE https://api.nativemsg.com/v1/humans/<human_id>/subscription

The successful unsubscription of a human from a channel will return the object below.

HTTP DELETE Response

Parameter Description
channelId The id of the channel.
humanId The id of the human.
subscription The human’s subscription state in the channel.

Get a Human Subscription Status in a Channel

Get a Human Subscription Status in a Channel Request:

curl "https://api.nativemsg.com/v1/humans/542/subscription"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/humans/542/subscription");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/humans/542/subscription", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/humans/542/subscription");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/humans/542/subscription");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/humans/542/subscription',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Get a Human Subscription Status in a Channel Response:

200 OK

{
    "channnelId": 551,
    "humanId": 542,
    "subscription": true
}

This endpoint will return a human subscription status in channel.

HTTP GET Request

GET https://api.nativemsg.com/v1/humans/<human_id>/subscription

HTTP GET Response

Parameter Description
channelId The id of the channel.
humanId The id of the human.
subscription The human’s subscription state in the channel.

Messages

NativeMsg allows you to send many different types of messages to users on any of the enabled channels in your account. Messages will be formatted according to the supported capabilities of the delivery channel.

Below is a list of commonly used components when sending messages and an example sending each type of message.

Message Properties

A list of various object and properties used when sending or receiving a message.

Message Object Properties

Parameter Description
text The text of the message - 640 characters max
mediaType image”, “audio”, video“ or ”file
media The full URL of the media content (image, video, audio or file)
targets An array of Target Objects of recipients
buttons An array of Button Objects
quickReplies An array of Quick Replies Objects
carousel An array of Carousel Objects
list An array of List Objects

Target Object Properties

Parameter Description
targetType Value can be ”humans“, ”flows“, ”channels“ and ”tags“.
ids An array of the targetType ids
subscription Boolean value can be used along with ”channels“ targetType only. Message sending will proceed for humans subscribed to their channel only.

Button Object Properties

Parameter Description
type The type of button - ”weburl“, ”postback“, ”call“ - required
title The text of the button - 20 character max, required
payload The value for the pressed button depending on the type. weburl = the url that is opened, postback = the data sent back to the webhook - 1,000 character max, call = the phone number dialed. The format must have ”+“ prefix followed by the country code, area code and local number. For example, +13125551212.
execute The name of the interaction/action that will be executed when this button is pressed. for type "postback”, optional

You may have up to a max of 3 buttons per message

Quick Replies Object Properties

Parameter Description
type The type of reply - “text”, “location” - required
title The text of the reply - 20 character max, required for type “text”
payload The value sent back to the webhook when the button is pressed - 1,000 character max, required for type “text”
execute The name of the interaction/action that will be executed when this quick reply is chosen. for type “text”, optional
imageUrl The URL of the image for text replies - optional

You may have up to a max of 11 quick replies per message

Parameter Description
title The title of an individual bubble - 80 character max, required
subtitle The subtitle of an individual bubble - 80 character max
imageUrl The URL to the image of the bubble
defaultAction A Default Action Object to trigger when the element is pressed
buttons An array of Button Objects. Button type share can only be used inside carousels. optional, max 3 buttons

You may have up to a max of 10 items per message and at least 1 is required.

Default Action Object Properties

Parameter Description
type The type must equal weburl
payload The URL that is opened in the browser - required

List Object Properties

Parameter Description
title The title of the element - 80 character max, required
subtitle The subtitle of the element - 80 character max
imageUrl The URL to the image of the list item - optional
defaultAction A Default Action Object to trigger when the element is pressed
button A Button Objects - optional, max 1 button

You may between 2 and 4 items and at least required.

A List Message can have an optional Button object outside the List Object array.

Get a List of Messages

List Messages Request:

curl "https://api.nativemsg.com/v1/messages/requests/{request_id}"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/messages/requests/{request_id}");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/messages/requests/{request_id}", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/messages/requests/{request_id}");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages/requests/{request_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages/requests/{request_id}',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

List Messages Response:

200 OK

[
  {
    "id":8767223,
    "flowId":56456,
    "channelId":5377889,
    "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m",
    "humandId":5667322,
    "sent":"2017-02-24T18:00:44",
    "status":"D",
    "messageType":"O",
    "delivered":"2017-02-24T18:00:44",
    "profilePic":"https://example.com/pictureOfMe.jpg",
    "message":
      {
        "text":"This is a message that will go out to humans.",
        "media":"https://example.com/pictureOfSomething.png"
      }
  },
]

The endpoint will return an array of Messages associated with a Send Message request. When a message is sent via a Send Message API call, the HTTP response will contain a request id that can be used to check the status of a message. Since a single message request can include multiple recipients, a request id will produce an array of messages associated to a request.

HTTP GET Request

GET https://api.nativemsg.com/v1/messages/requests/{request_id}

Get Message Response

Parameter Description
id The id of the message
flowId The Flow that is associated to this message.
channelId The Channel that is associated to this message.
requestId The id of the request that sent this message.
humanId The id of the Human that received this message.
sent The date and time the Message was sent. Format yyyy-mm-ddThh:mm:ss in GMT 0.
status The current status of the message - “A” = Accepted, “P” = Pending, “S” = Sent, “D” = Delivered, “F” = Failed, “Q” = Queued/Scheduled.
messageType The type of message - “O” = Outbound to Human, “I” = Inbound to NativeMsg, “B” = Outbound blast to many.
delivered The date and time the Message was delivered. Format yyyy-mm-ddThh:mm:ss in GMT 0.
profilePicUrl The URL of the sender’s picture.
message A Message Object with the contents of the message.

Get a Message

Message Request:

curl "https://api.nativemsg.com/v1/messages/{message_id}"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/messages/{message_id}");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/messages/{message_id}", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/messages/{message_id}");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages/{message_id}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages/{message_id}',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Message Response:

200 OK

{
  "id":8767223,
  "flowId":56456,
  "channelId":5377889,
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m",
  "humandId":5667322,
  "sent":"2017-02-24T18:00:44",
  "status":"D",
  "messageType":"O",
  "delivered":"2017-02-24T18:00:44",
  "profilePic":"https://example.com/pictureOfMe.jpg",
  "message":
    {
      "text":"This is a message that will go out to humans.",
      "media":"https://example.com/pictureOfSomething.png"
    }
}

The endpoint will return the details of an individual message by message id.

HTTP GET Request

GET https://api.nativemsg.com/v1/messages/{message_id}

Get Message Response

Parameter Description
id The id of the message
flowId The Flow that is associated to this message.
channelId The Channel that is associated to this message.
requestId The id of the request that sent this message.
humanId The id of the Human that received this message.
sent The date and time the Message was sent. Format yyyy-mm-ddThh:mm:ss in GMT 0.
status The current status of the message - “A” = Accepted, “P” = Pending, “S” = Sent, “D” = Delivered, “F” = Failed, “Q” = Queued/Scheduled.
messageType The type of message - “O” = Outbound to Human, “I” = Inbound to NativeMsg, “B” = Outbound blast to many.
delivered The date and time the Message was delivered. Format yyyy-mm-ddThh:mm:ss in GMT 0.
profilePicUrl The URL of the sender’s picture.
message A Message Object with the contents of the message.

Send a Message

Send Message Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"text\": \"This is a message that will go out to humans.\",
      \"mediaType\":\"image\",
      \"media\":\"https://example.com/pictureOfSomething.png\",
      \"targets\":
        [{\"targetType\": \"humans\",
          \"ids\": [15,435,345345,23142]}
        ]
      }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"text\": \"This is a message that will go out to humans.\"," +
            "\"mediaType\": \"image\"," +
            "\"media\": \"https://example.com/pictureOfSomething.png\"," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "15," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "text": "This is a message that will go out to humans.",
    "mediaType": "image",
    "media": "https://example.com/pictureOfSomething.png",
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                15,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""text"": ""This is a message that will go out to humans."",
            ""mediaType"": ""image"",
            ""media"": ""https://example.com/pictureOfSomething.png"",
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        15,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'text' => 'This is a message that will go out to humans.',
    'mediaType' => 'image',
    'media' => 'https://example.com/pictureOfSomething.png',
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                15,
                435,
                345345,
                23142
            ]
        ]
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    text: 'This is a message that will go out to humans.',
    mediaType: 'image',
    media: 'https://example.com/pictureOfSomething.png',
    targets: [
        {
            targetType: 'humans',
            ids: [
                15,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

This endpoint will allow you to send a message to a human. Below are many examples of sending different types of messages.

HTTP Post Request

POST https://api.nativemsg.com/v1/messages

POST JSON Payload

Use the Message Object as the payload for sending a message.

Send Message Response

Parameter Description
requestId The id of the send message request. This id can be used to retrieve the status of a message.

Send a Simple Text Message

Send a Simple Text Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"text\": \"This is a message that will go out to humans.\",
      \"targets\":
        [{\"targetType\": \"humans\",
          \"ids\": [13,435,345345,23142]}
        ]
      }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"text\": \"This is a message that will go out to humans.\"," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "13," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "text": "This is a message that will go out to humans.",
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                13,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""text"": ""This is a message that will go out to humans."",
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        13,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'text' => 'This is a message that will go out to humans.',
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                13,
                435,
                345345,
                23142
            ]
        ]
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    text: 'This is a message that will go out to humans.',
    targets: [
        {
            targetType: 'humans',
            ids: [
                13,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

Send a simple message with only text to a human.

Supported Channels

Channel Type Description
Facebook fb
Text Us tus
SMS sms
Twitter twr
Alexa alx

Send a Media Message

Send a Media Message Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"mediaType\":\"image\",
      \"media\":\"https://example.com/pictureOfSomething.png\",
      \"targets\":
        [{\"targetType\": \"humans\",
          \"ids\": [12,435,345345,23142]}
        ]
      }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"mediaType\": \"image\"," +
            "\"media\": \"https://example.com/pictureOfSomething.png\"," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "12," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "mediaType": "image",
    "media": "https://example.com/pictureOfSomething.png",
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""mediaType"": ""image"",
            ""media"": ""https://example.com/pictureOfSomething.png"",
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        12,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'mediaType' => 'image',
    'media' => 'https://example.com/pictureOfSomething.png',
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                12,
                435,
                345345,
                23142
            ]
        ]
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    mediaType: 'image',
    media: 'https://example.com/pictureOfSomething.png',
    targets: [
        {
            targetType: 'humans',
            ids: [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

Send a media message with an image, video, audio or file to a human.

Supported Channels

Channel Type Description
Facebook fb
Text Us tus
Twitter twr

Send a Media Message w/ Text

Send a Media and Text Message Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"text\": \"This is a message that will go out to humans.\",
      \"mediaType\":\"image\",
      \"media\":\"https://example.com/pictureOfSomething.png\",
      \"targets\":
        [{\"targetType\": \"humans\",
          \"ids\": [14,435,345345,23142]}
        ]
      }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"text\": \"This is a message that will go out to humans.\"," +
            "\"mediaType\": \"image\"," +
            "\"media\": \"https://example.com/pictureOfSomething.png\"," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "14," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "text": "This is a message that will go out to humans.",
    "mediaType": "image",
    "media": "https://example.com/pictureOfSomething.png",
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                14,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""text"": ""This is a message that will go out to humans."",
            ""mediaType"": ""image"",
            ""media"": ""https://example.com/pictureOfSomething.png"",
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        14,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'text' => 'This is a message that will go out to humans.',
    'mediaType' => 'image',
    'media' => 'https://example.com/pictureOfSomething.png',
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                14,
                435,
                345345,
                23142
            ]
        ]
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    text: 'This is a message that will go out to humans.',
    mediaType: 'image',
    media: 'https://example.com/pictureOfSomething.png',
    targets: [
        {
            targetType: 'humans',
            ids: [
                14,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

Send a media message with an image, video, audio or file to a human.

Supported Channels

Channel Type Description
Facebook fb
Text Us tus
Twitter twr

Send a Message w/ Buttons

Send a Media Message with Buttons Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{
        \"text\": \"This is a message with buttons below.\",
        \"buttons\": [{
          \"type\": \"weburl\",
          \"title\": \"nativeMsg site\",
          \"payload\":\"http://nativemsg.com\"
        }, {
          \"type\": \"postback\",
          \"title\": \"Postback\",
          \"payload\": \"POSTBACK_PAYLOAD\"
        }, {
          \"type\": \"call\",
          \"title\": \"Call\",
          \"payload\": \"+18885776577\"
        }],
        \"targets\":
          [{\"targetType\": \"humans\",
            \"ids\": [12,435,345345,23142]}
          ]
      }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"text\": \"This is a message with buttons below.\"," +
            "\"buttons\": [" +
                "{" +
                    "\"type\": \"weburl\"," +
                    "\"title\": \"nativeMsg site\"," +
                    "\"payload\": \"http://nativemsg.com\"" +
                "}," +
                "{" +
                    "\"type\": \"postback\"," +
                    "\"title\": \"Postback\"," +
                    "\"payload\": \"POSTBACK_PAYLOAD\"" +
                "}," +
                "{" +
                    "\"type\": \"call\"," +
                    "\"title\": \"Call\"," +
                    "\"payload\": \"+18885776577\"" +
                "}" +
            "]," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "12," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "text": "This is a message with buttons below.",
    "buttons": [
        {
            "type": "weburl",
            "title": "nativeMsg site",
            "payload": "http://nativemsg.com"
        },
        {
            "type": "postback",
            "title": "Postback",
            "payload": "POSTBACK_PAYLOAD"
        },
        {
            "type": "call",
            "title": "Call",
            "payload": "+18885776577"
        }
    ],
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""text"": ""This is a message with buttons below."",
            ""buttons"": [
                {
                    ""type"": ""weburl"",
                    ""title"": ""nativeMsg site"",
                    ""payload"": ""http://nativemsg.com""
                },
                {
                    ""type"": ""postback"",
                    ""title"": ""Postback"",
                    ""payload"": ""POSTBACK_PAYLOAD""
                },
                {
                    ""type"": ""call"",
                    ""title"": ""Call"",
                    ""payload"": ""+18885776577""
                }
            ],
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        12,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'text' => 'This is a message with buttons below.',
    'buttons' => [
        {
            'type' => 'weburl',
            'title' => 'nativeMsg site',
            'payload' => 'http://nativemsg.com'
        ],
        {
            'type' => 'postback',
            'title' => 'Postback',
            'payload' => 'POSTBACK_PAYLOAD'
        },
        {
            'type' => 'call',
            'title' => 'Call',
            'payload' => '+18885776577'
        }
    ],
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    text: 'This is a message with buttons below.',
    buttons: [
        {
            type: 'weburl',
            title: 'nativeMsg site',
            payload: 'http://nativemsg.com'
        },
        {
            type: 'postback',
            title: 'Postback',
            payload: 'POSTBACK_PAYLOAD'
        },
        {
            type: 'call',
            title: 'Call',
            payload: '+18885776577'
        }
    ],
    targets: [
        {
            targetType: 'humans',
            ids: [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

Send a message with buttons.

Supported Channels

Channel Type Description
Facebook fb

Send a Message w/ Quick Replies

Send a Message with Quick Replies Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{
        \"text\": \"This is a message with quick replies below.\",
        \"quickReplies\":
        [{
            \"type\": \"text\",
            \"title\": \"Payload Option\",
            \"payload\": \"payload\"
          }, {
            \"type\": \"text\",
            \"title\": \"Payload and Image\",
            \"payload\": \"payload\",
            \"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"
          }, {
            \"type\": \"location\"
          }, {
            \"type\": \"location\",
            \"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"
        }],
        \"targets\":
          [{\"targetType\": \"humans\",
            \"ids\": [12,435,345345,23142]}
          ]
      }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"text\": \"This is a message with quick replies below.\"," +
            "\"quickReplies\": [" +
                "{" +
                    "\"type\": \"text\"," +
                    "\"title\": \"Payload Option\"," +
                    "\"payload\": \"payload\"" +
                "}," +
                "{" +
                    "\"type\": \"text\"," +
                    "\"title\": \"Payload and Image\"," +
                    "\"payload\": \"payload\"," +
                    "\"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"" +
                "}," +
                "{" +
                    "\"type\": \"location\"" +
                "}," +
                "{" +
                    "\"type\": \"location\"," +
                    "\"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"" +
                "}" +
            "]," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "12," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "text": "This is a message with quick replies below.",
    "quickReplies": [
        {
            "type": "text",
            "title": "Payload Option",
            "payload": "payload"
        },
        {
            "type": "text",
            "title": "Payload and Image",
            "payload": "payload",
            "imageUrl": "http://nativemsg.com/assets/images/icon-con.png"
        },
        {
            "type": "location"
        },
        {
            "type": "location",
            "imageUrl": "http://nativemsg.com/assets/images/icon-con.png"
        }
    ],
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""text"": ""This is a message with quick replies below."",
            ""quickReplies"": [
                {
                    ""type"": ""text"",
                    ""title"": ""Payload Option"",
                    ""payload"": ""payload""
                },
                {
                    ""type"": ""text"",
                    ""title"": ""Payload and Image"",
                    ""payload"": ""payload"",
                    ""imageUrl"": ""http://nativemsg.com/assets/images/icon-con.png""
                },
                {
                    ""type"": ""location""
                },
                {
                    ""type"": ""location"",
                    ""imageUrl"": ""http://nativemsg.com/assets/images/icon-con.png""
                }
            ],
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        12,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'text' => 'This is a message with quick replies below.',
    'quickReplies' => [
        {
            'type' => 'text',
            'title' => 'Payload Option',
            'payload' => 'payload'
        ],
        {
            'type' => 'text',
            'title' => 'Payload and Image',
            'payload' => 'payload',
            'imageUrl' => 'http://nativemsg.com/assets/images/icon-con.png'
        },
        {
            'type' => 'location'
        },
        {
            'type' => 'location',
            'imageUrl' => 'http://nativemsg.com/assets/images/icon-con.png'
        }
    ],
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    text: 'This is a message with quick replies below.',
    quickReplies: [
        {
            type: 'text',
            title: 'Payload Option',
            payload: 'payload'
        },
        {
            type: 'text',
            title: 'Payload and Image',
            payload: 'payload',
            imageUrl: 'http://nativemsg.com/assets/images/icon-con.png'
        },
        {
            type: 'location'
        },
        {
            type: 'location',
            imageUrl: 'http://nativemsg.com/assets/images/icon-con.png'
        }
    ],
    targets: [
        {
            targetType: 'humans',
            ids: [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

An example of sending a message with quick reply button options.

Supported Channels

Channel Type Description
Facebook fb
Twitter twr

Send a Media Message w/ Quick Replies

Send a Media Message with Quick Replies Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"mediaType\":\"image\",
      \"media\":\"https://example.com/pictureOfSomething.png\",
      \"quickReplies\": [{
          \"type\": \"text\",
          \"title\": \"Payload Option\",
          \"payload\": \"payload\"
        }, {
          \"type\": \"text\",
          \"title\": \"Payload and Image\",
          \"payload\": \"payload\",
          \"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"
        }, {
          \"type\": \"location\"
        }, {
          \"type\": \"location\",
          \"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"
      }],
      \"targets\":
        [{\"targetType\": \"humans\",
          \"ids\": [12,435,345345,23142]}
        ]
      }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"mediaType\": \"image\"," +
            "\"media\": \"https://example.com/pictureOfSomething.png\"," +
            "\"quickReplies\": [" +
                "{" +
                    "\"type\": \"text\"," +
                    "\"title\": \"Payload Option\"," +
                    "\"payload\": \"payload\"" +
                "}," +
                "{" +
                    "\"type\": \"text\"," +
                    "\"title\": \"Payload and Image\"," +
                    "\"payload\": \"payload\"," +
                    "\"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"" +
                "}," +
                "{" +
                    "\"type\": \"location\"" +
                "}," +
                "{" +
                    "\"type\": \"location\"," +
                    "\"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"" +
                "}" +
            "]," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "12," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "mediaType": "image",
    "media": "https://example.com/pictureOfSomething.png",
    "quickReplies": [
        {
            "type": "text",
            "title": "Payload Option",
            "payload": "payload"
        },
        {
            "type": "text",
            "title": "Payload and Image",
            "payload": "payload",
            "imageUrl": "http://nativemsg.com/assets/images/icon-con.png"
        },
        {
            "type": "location"
        },
        {
            "type": "location",
            "imageUrl": "http://nativemsg.com/assets/images/icon-con.png"
        }
    ],
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""mediaType"": ""image"",
            ""media"": ""https://example.com/pictureOfSomething.png"",
            ""quickReplies"": [
                {
                    ""type"": ""text"",
                    ""title"": ""Payload Option"",
                    ""payload"": ""payload""
                },
                {
                    ""type"": ""text"",
                    ""title"": ""Payload and Image"",
                    ""payload"": ""payload"",
                    ""imageUrl"": ""http://nativemsg.com/assets/images/icon-con.png""
                },
                {
                    ""type"": ""location""
                },
                {
                    ""type"": ""location"",
                    ""imageUrl"": ""http://nativemsg.com/assets/images/icon-con.png""
                }
            ],
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        12,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'mediaType' => 'image',
    'media' => 'https://example.com/pictureOfSomething.png',
    'quickReplies' => [
        {
            'type' => 'text',
            'title' => 'Payload Option',
            'payload' => 'payload'
        ],
        {
            'type' => 'text',
            'title' => 'Payload and Image',
            'payload' => 'payload',
            'imageUrl' => 'http://nativemsg.com/assets/images/icon-con.png'
        },
        {
            'type' => 'location'
        },
        {
            'type' => 'location',
            'imageUrl' => 'http://nativemsg.com/assets/images/icon-con.png'
        }
    ],
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    mediaType: 'image',
    media: 'https://example.com/pictureOfSomething.png',
    quickReplies: [
        {
            type: 'text',
            title: 'Payload Option',
            payload: 'payload'
        },
        {
            type: 'text',
            title: 'Payload and Image',
            payload: 'payload',
            imageUrl: 'http://nativemsg.com/assets/images/icon-con.png'
        },
        {
            type: 'location'
        },
        {
            type: 'location',
            imageUrl: 'http://nativemsg.com/assets/images/icon-con.png'
        }
    ],
    targets: [
        {
            targetType: 'humans',
            ids: [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

An example of sending a media message with buttons below.

Supported Channels

Channel Type Description
Facebook fb

Send a Carousel Message Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{
  \"carousel\": [{
    \"title\": \"Title 1\",
    \"subtitle\": \"Subtitle of 1\",
    \"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\",
    \"defaultAction\": {
      \"type\": \"weburl\",
      \"payload\": \"http://nativemsg.com\"
    },
    \"buttons\": [{
      \"type\": \"weburl\",
      \"title\": \"nativeMsg Site\",
      \"payload\":\"http://nativemsg.com\"
    }, {
      \"type\": \"postback\",
      \"title\": \"Postback\",
      \"payload\": \"POSTBACK_PAYLOAD\"
    }, {
      \"type\": \"share\"
    }]
  }, {
    \"title\": \"Title 2\",
    \"subtitle\": \"Subtitle of 2\",
    \"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\",
    \"defaultAction\": {
      \"type\": \"weburl\",
      \"payload\": \"http://nativemsg.com\"
    },
    \"buttons\": [{
      \"type\": \"weburl\",
      \"title\": \"nativeMsg Site\",
      \"payload\":\"http://nativemsg.com\"
    }, {
      \"type\": \"postback\",
      \"title\": \"Postback\",
      \"payload\": \"POSTBACK_PAYLOAD\"
    }, {
      \"type\": \"share\"
    }]
  }],
  \"targets\": [{
    \"targetType\": \"humans\",
    \"ids\": [12,435,345345,23142]
  }]
}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"carousel\": [" +
                "{" +
                    "\"title\": \"Title 1\"," +
                    "\"subtitle\": \"Subtitle of 1\"," +
                    "\"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"," +
                    "\"defaultAction\": {" +
                        "\"type\": \"weburl\"," +
                        "\"payload\": \"http://nativemsg.com\"" +
                    "}," +
                    "\"buttons\": [" +
                        "{" +
                            "\"type\": \"weburl\"," +
                            "\"title\": \"nativeMsg Site\"," +
                            "\"payload\": \"http://nativemsg.com\"" +
                        "}," +
                        "{" +
                            "\"type\": \"postback\"," +
                            "\"title\": \"Postback\"," +
                            "\"payload\": \"POSTBACK_PAYLOAD\"" +
                        "}," +
                        "{" +
                            "\"type\": \"share\"" +
                        "}" +
                    "]" +
                "}," +
                "{" +
                    "\"title\": \"Title 2\"," +
                    "\"subtitle\": \"Subtitle of 2\"," +
                    "\"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"," +
                    "\"defaultAction\": {" +
                        "\"type\": \"weburl\"," +
                        "\"payload\": \"http://nativemsg.com\"" +
                    "}," +
                    "\"buttons\": [" +
                        "{" +
                            "\"type\": \"weburl\"," +
                            "\"title\": \"nativeMsg Site\"," +
                            "\"payload\": \"http://nativemsg.com\"" +
                        "}," +
                        "{" +
                            "\"type\": \"postback\"," +
                            "\"title\": \"Postback\"," +
                            "\"payload\": \"POSTBACK_PAYLOAD\"" +
                        "}," +
                        "{" +
                            "\"type\": \"share\"" +
                        "}" +
                    "]" +
                "}" +
            "]," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "12," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "carousel": [
        {
            "title": "Title 1",
            "subtitle": "Subtitle of 1",
            "imageUrl": "http://nativemsg.com/assets/images/icon-con.png",
            "defaultAction": {
                "type": "weburl",
                "payload": "http://nativemsg.com"
            },
            "buttons": [
                {
                    "type": "weburl",
                    "title": "nativeMsg Site",
                    "payload": "http://nativemsg.com"
                },
                {
                    "type": "postback",
                    "title": "Postback",
                    "payload": "POSTBACK_PAYLOAD"
                },
                {
                    "type": "share"
                }
            ]
        },
        {
            "title": "Title 2",
            "subtitle": "Subtitle of 2",
            "imageUrl": "http://nativemsg.com/assets/images/icon-con.png",
            "defaultAction": {
                "type": "weburl",
                "payload": "http://nativemsg.com"
            },
            "buttons": [
                {
                    "type": "weburl",
                    "title": "nativeMsg Site",
                    "payload": "http://nativemsg.com"
                },
                {
                    "type": "postback",
                    "title": "Postback",
                    "payload": "POSTBACK_PAYLOAD"
                },
                {
                    "type": "share"
                }
            ]
        }
    ],
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""carousel"": [
                {
                    ""title"": ""Title 1"",
                    ""subtitle"": ""Subtitle of 1"",
                    ""imageUrl"": ""http://nativemsg.com/assets/images/icon-con.png"",
                    ""defaultAction"": {
                        ""type"": ""weburl"",
                        ""payload"": ""http://nativemsg.com""
                    },
                    ""buttons"": [
                        {
                            ""type"": ""weburl"",
                            ""title"": ""nativeMsg Site"",
                            ""payload"": ""http://nativemsg.com""
                        },
                        {
                            ""type"": ""postback"",
                            ""title"": ""Postback"",
                            ""payload"": ""POSTBACK_PAYLOAD""
                        },
                        {
                            ""type"": ""share""
                        }
                    ]
                },
                {
                    ""title"": ""Title 2"",
                    ""subtitle"": ""Subtitle of 2"",
                    ""imageUrl"": ""http://nativemsg.com/assets/images/icon-con.png"",
                    ""defaultAction"": {
                        ""type"": ""weburl"",
                        ""payload"": ""http://nativemsg.com""
                    },
                    ""buttons"": [
                        {
                            ""type"": ""weburl"",
                            ""title"": ""nativeMsg Site"",
                            ""payload"": ""http://nativemsg.com""
                        },
                        {
                            ""type"": ""postback"",
                            ""title"": ""Postback"",
                            ""payload"": ""POSTBACK_PAYLOAD""
                        },
                        {
                            ""type"": ""share""
                        }
                    ]
                }
            ],
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        12,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'carousel' => [
        {
            'title' => 'Title 1',
            'subtitle' => 'Subtitle of 1',
            'imageUrl' => 'http://nativemsg.com/assets/images/icon-con.png',
            'defaultAction' => {
                'type' => 'weburl',
                'payload' => 'http://nativemsg.com'
            ],
            'buttons' => [
                {
                    'type' => 'weburl',
                    'title' => 'nativeMsg Site',
                    'payload' => 'http://nativemsg.com'
                },
                {
                    'type' => 'postback',
                    'title' => 'Postback',
                    'payload' => 'POSTBACK_PAYLOAD'
                },
                {
                    'type' => 'share'
                }
            ]
        },
        {
            'title' => 'Title 2',
            'subtitle' => 'Subtitle of 2',
            'imageUrl' => 'http://nativemsg.com/assets/images/icon-con.png',
            'defaultAction' => {
                'type' => 'weburl',
                'payload' => 'http://nativemsg.com'
            },
            'buttons' => [
                {
                    'type' => 'weburl',
                    'title' => 'nativeMsg Site',
                    'payload' => 'http://nativemsg.com'
                },
                {
                    'type' => 'postback',
                    'title' => 'Postback',
                    'payload' => 'POSTBACK_PAYLOAD'
                },
                {
                    'type' => 'share'
                }
            ]
        }
    ],
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    carousel: [
        {
            title: 'Title 1',
            subtitle: 'Subtitle of 1',
            imageUrl: 'http://nativemsg.com/assets/images/icon-con.png',
            defaultAction: {
                type: 'weburl',
                payload: 'http://nativemsg.com'
            },
            buttons: [
                {
                    type: 'weburl',
                    title: 'nativeMsg Site',
                    payload: 'http://nativemsg.com'
                },
                {
                    type: 'postback',
                    title: 'Postback',
                    payload: 'POSTBACK_PAYLOAD'
                },
                {
                    type: 'share'
                }
            ]
        },
        {
            title: 'Title 2',
            subtitle: 'Subtitle of 2',
            imageUrl: 'http://nativemsg.com/assets/images/icon-con.png',
            defaultAction: {
                type: 'weburl',
                payload: 'http://nativemsg.com'
            },
            buttons: [
                {
                    type: 'weburl',
                    title: 'nativeMsg Site',
                    payload: 'http://nativemsg.com'
                },
                {
                    type: 'postback',
                    title: 'Postback',
                    payload: 'POSTBACK_PAYLOAD'
                },
                {
                    type: 'share'
                }
            ]
        }
    ],
    targets: [
        {
            targetType: 'humans',
            ids: [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

An example of sending a carousel message.

Supported Channels

Channel Type Description
Facebook fb

Send a List Message

Send a List Message Request:

curl "https://api.nativemsg.com/v1/messages"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{
      \"list\": [{
        \"title\": \"Title 1\",
        \"subtitle\": \"Subtitle of 1\",
        \"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\",
        \"defaultAction\": {
          \"type\": \"weburl\",
          \"payload\": \"http://nativemsg.com\"
        },
        \"button\": {
          \"type\": \"weburl\",
          \"title\": \"nativeMsg Site\",
          \"payload\": \"http://nativemsg.com\"
        }
      }, {
        \"title\": \"Title 2\",
        \"subtitle\": \"Subtitle of 2\",
        \"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\",
        \"defaultAction\": {
          \"type\": \"weburl\",
          \"payload\": \"http://nativemsg.com\"
        },
        \"button\": {
          \"type\": \"postback\",
          \"title\": \"Postback\",
          \"payload\": \"POSTBACK_PAYLOAD\"
        }
      }],
      \"button\": {
          \"type\": \"weburl\",
          \"title\": \"nativeMsg Site\",
          \"payload\": \"http://nativemsg.com\"
      },
      \"targets\": [{
        \"targetType\": \"humans\",
        \"ids\": [12,435,345345,23142]
      }]
    }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"list\": [" +
                "{" +
                    "\"title\": \"Title 1\"," +
                    "\"subtitle\": \"Subtitle of 1\"," +
                    "\"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"," +
                    "\"defaultAction\": {" +
                        "\"type\": \"weburl\"," +
                        "\"payload\": \"http://nativemsg.com\"" +
                    "}," +
                    "\"button\": {" +
                        "\"type\": \"weburl\"," +
                        "\"title\": \"nativeMsg Site\"," +
                        "\"payload\": \"http://nativemsg.com\"" +
                    "}" +
                "}," +
                "{" +
                    "\"title\": \"Title 2\"," +
                    "\"subtitle\": \"Subtitle of 2\"," +
                    "\"imageUrl\": \"http://nativemsg.com/assets/images/icon-con.png\"," +
                    "\"defaultAction\": {" +
                        "\"type\": \"weburl\"," +
                        "\"payload\": \"http://nativemsg.com\"" +
                    "}," +
                    "\"button\": {" +
                        "\"type\": \"postback\"," +
                        "\"title\": \"Postback\"," +
                        "\"payload\": \"POSTBACK_PAYLOAD\"" +
                    "}" +
                "}" +
            "]," +
            "\"button\": {" +
                "\"type\": \"weburl\"," +
                "\"title\": \"nativeMsg Site\"," +
                "\"payload\": \"http://nativemsg.com\"" +
            "}," +
            "\"targets\": [" +
                "{" +
                    "\"targetType\": \"humans\"," +
                    "\"ids\": [" +
                        "12," +
                        "435," +
                        "345345," +
                        "23142" +
                    "]" +
                "}" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "list": [
        {
            "title": "Title 1",
            "subtitle": "Subtitle of 1",
            "imageUrl": "http://nativemsg.com/assets/images/icon-con.png",
            "defaultAction": {
                "type": "weburl",
                "payload": "http://nativemsg.com"
            },
            "button": {
                "type": "weburl",
                "title": "nativeMsg Site",
                "payload": "http://nativemsg.com"
            }
        },
        {
            "title": "Title 2",
            "subtitle": "Subtitle of 2",
            "imageUrl": "http://nativemsg.com/assets/images/icon-con.png",
            "defaultAction": {
                "type": "weburl",
                "payload": "http://nativemsg.com"
            },
            "button": {
                "type": "postback",
                "title": "Postback",
                "payload": "POSTBACK_PAYLOAD"
            }
        }
    ],
    "button": {
        "type": "weburl",
        "title": "nativeMsg Site",
        "payload": "http://nativemsg.com"
    },
    "targets": [
        {
            "targetType": "humans",
            "ids": [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}"""
connection.request("POST", "/v1/messages", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""list"": [
                {
                    ""title"": ""Title 1"",
                    ""subtitle"": ""Subtitle of 1"",
                    ""imageUrl"": ""http://nativemsg.com/assets/images/icon-con.png"",
                    ""defaultAction"": {
                        ""type"": ""weburl"",
                        ""payload"": ""http://nativemsg.com""
                    },
                    ""button"": {
                        ""type"": ""weburl"",
                        ""title"": ""nativeMsg Site"",
                        ""payload"": ""http://nativemsg.com""
                    }
                },
                {
                    ""title"": ""Title 2"",
                    ""subtitle"": ""Subtitle of 2"",
                    ""imageUrl"": ""http://nativemsg.com/assets/images/icon-con.png"",
                    ""defaultAction"": {
                        ""type"": ""weburl"",
                        ""payload"": ""http://nativemsg.com""
                    },
                    ""button"": {
                        ""type"": ""postback"",
                        ""title"": ""Postback"",
                        ""payload"": ""POSTBACK_PAYLOAD""
                    }
                }
            ],
            ""button"": {
                ""type"": ""weburl"",
                ""title"": ""nativeMsg Site"",
                ""payload"": ""http://nativemsg.com""
            },
            ""targets"": [
                {
                    ""targetType"": ""humans"",
                    ""ids"": [
                        12,
                        435,
                        345345,
                        23142
                    ]
                }
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'list' => [
        {
            'title' => 'Title 1',
            'subtitle' => 'Subtitle of 1',
            'imageUrl' => 'http://nativemsg.com/assets/images/icon-con.png',
            'defaultAction' => {
                'type' => 'weburl',
                'payload' => 'http://nativemsg.com'
            ],
            'button' => {
                'type' => 'weburl',
                'title' => 'nativeMsg Site',
                'payload' => 'http://nativemsg.com'
            }
        },
        {
            'title' => 'Title 2',
            'subtitle' => 'Subtitle of 2',
            'imageUrl' => 'http://nativemsg.com/assets/images/icon-con.png',
            'defaultAction' => {
                'type' => 'weburl',
                'payload' => 'http://nativemsg.com'
            },
            'button' => {
                'type' => 'postback',
                'title' => 'Postback',
                'payload' => 'POSTBACK_PAYLOAD'
            }
        }
    ],
    'button' => {
        'type' => 'weburl',
        'title' => 'nativeMsg Site',
        'payload' => 'http://nativemsg.com'
    },
    'targets' => [
        {
            'targetType' => 'humans',
            'ids' => [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    list: [
        {
            title: 'Title 1',
            subtitle: 'Subtitle of 1',
            imageUrl: 'http://nativemsg.com/assets/images/icon-con.png',
            defaultAction: {
                type: 'weburl',
                payload: 'http://nativemsg.com'
            },
            button: {
                type: 'weburl',
                title: 'nativeMsg Site',
                payload: 'http://nativemsg.com'
            }
        },
        {
            title: 'Title 2',
            subtitle: 'Subtitle of 2',
            imageUrl: 'http://nativemsg.com/assets/images/icon-con.png',
            defaultAction: {
                type: 'weburl',
                payload: 'http://nativemsg.com'
            },
            button: {
                type: 'postback',
                title: 'Postback',
                payload: 'POSTBACK_PAYLOAD'
            }
        }
    ],
    button: {
        type: 'weburl',
        title: 'nativeMsg Site',
        payload: 'http://nativemsg.com'
    },
    targets: [
        {
            targetType: 'humans',
            ids: [
                12,
                435,
                345345,
                23142
            ]
        }
    ]
}));
request.end();

Send Message Response:

200 OK

{
  "requestId":"jh2h4hKj3Khjaak123jhgvn1v12n31m"
}

An example of sending a list message to humans.

Supported Channels

Channel Type Description
Facebook fb

Process a Message

Process a Message Request:

curl "https://api.nativemsg.com/v1/messages/process"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"text\": \"This is a message that will be processed by the bot.\",
      \"channelUuid\": \"3e568f4e-667e-47f1-9e0e-f8338bae8813\",
      \"humanUuid\": \"bfc28744-90f2-4b2b-b568-305e85812319\"
      }"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/messages/process");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"text\": \"This is a message that will be processed by the bot.\"," +
            "\"channelUuid\": \"3e568f4e-667e-47f1-9e0e-f8338bae8813\"," +
            "\"humanUuid\": \"bfc28744-90f2-4b2b-b568-305e85812319\"" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "text": "This is a message that will be processed by the bot.",
    "channelUuid": "3e568f4e-667e-47f1-9e0e-f8338bae8813",
    "humanUuid": "bfc28744-90f2-4b2b-b568-305e85812319"
}"""
connection.request("POST", "/v1/messages/process", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""text"": ""This is a message that will be processed by the bot."",
            ""channelUuid"": ""3e568f4e-667e-47f1-9e0e-f8338bae8813"",
            ""humanUuid"": ""bfc28744-90f2-4b2b-b568-305e85812319""
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/messages/process", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/messages/process");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'text' => 'This is a message that will be processed by the bot.',
    'channelUuid' => '3e568f4e-667e-47f1-9e0e-f8338bae8813',
    'humanUuid' => 'bfc28744-90f2-4b2b-b568-305e85812319'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/messages/process',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    text: 'This is a message that will be processed by the bot.',
    channelUuid: '3e568f4e-667e-47f1-9e0e-f8338bae8813',
    humanUuid: 'bfc28744-90f2-4b2b-b568-305e85812319'
}));
request.end();

Process Message Response:

200 OK

{
  "humanUuid": "bfc28744-90f2-4b2b-b568-305e85812319",
  "messages": [
    {
      "text": "message from bot #1"
    },
    {
      "text": "message from bot #2",
      "buttons": [
        {
          "type": "postback",
          "title": "button",
          "execute": "action"
        }
      ]
    }
  ]
}

This endpoint allows a user to process an inbound message by the bot. All messages that are send by the bot are returned back in the response.

HTTP Post Request

POST https://api.nativemsg.com/v1/messages/process

POST JSON Payload Message Object Properties

Parameter Description
channelUuid UUID of the channel.
humanUuid UUID of the human. Will be generated if not specified.
text The text of the message.
mediaType image”, “audio”, video“ or ”file“.
media The full URL of the media content (image, video, audio or file).
getStarted Can be used to display start message.
payload The value for the pressed button.
execute The name of the interaction/action to execute.
coordinates Can be used to send object with latitude and longitude values as response to location request.
quickReply Should be set to true when message is behaved as quick reply.

Process Message Response

Parameter Description
humanUuid UUID of the human.
messages An array of Message Objects

Supported Channels

Channel Type Description
Web chat web

Tags

Get a List of Tags

List Tags Request:

curl "https://api.nativemsg.com/v1/tags"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/tags");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/tags", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/tags");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/tags");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/tags',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

List Tags Response:

200 OK

[
  {
    "id": 4,
    "name": "tag0",
    "description": "tag0",
    "dateCreated": "2017-12-27T13:55:14"
  },
]

The endpoint will return an array of Tags created in your account.

HTTP GET Request

GET https://api.nativemsg.com/v1/tags

Get Tags List Response

Parameter Description
id The id of the Tag.
name The name of the Tag. Is unique for user account.
description The description of the Tag.
dateCreated The date and time the Tag was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Get a List of Tags Assigned to Humans

List of Tags Assigned to Humans Request:

curl "https://api.nativemsg.com/v1/tags?humanIds=540,542"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/tags?humanIds=540,542");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/tags?humanIds=540,542", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/tags?humanIds=540,542");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/tags?humanIds=540,542");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/tags?humanIds=540,542',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

List of Tags Assigned to Humans Response:

200 OK

[
  {
    "id": 4,
    "name": "tag0",
    "description": "tag0",
    "dateCreated": "2017-12-27T13:55:14",
    "dateUpdated": "2018-01-16T12:02:16"
  },
]

The endpoint will return an array of Tags assigned to humans.

HTTP GET Request

GET https://api.nativemsg.com/v1/tags?humanIds={human_ids}

Query String Parameters

Parameter Description
humanIds Coma separated human ids.

The successful request will return the array of objects below.

HTTP GET Response

Parameter Description
id The id of the Tag.
name The name of the Tag. Should be unique for user account.
description The description of the Tag.
dateCreated The date and time the Tag was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
dateUpdated The date and time the Tag was last updated. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Get a Tag

Tag Request:

curl "https://api.nativemsg.com/v1/tags/4"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/tags/4");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/tags/4", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/tags/4");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/tags/4");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/tags/4',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Tag Response:

200 OK

{
  "id": 4,
  "name": "tag0",
  "description": "tag0",
  "dateCreated": "2017-12-27T13:55:14"
}

The endpoint will get a single Tag by id.

HTTP GET Request

GET https://api.nativemsg.com/v1/tags/{tag_id}

Get Tag Response

Parameter Description
id The id of the Tag.
name The name of the Tag. Is unique for user account.
description The description of the Tag.
dateCreated The date and time the Tag was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Add a Tag

Add Tag Request:

curl "https://api.nativemsg.com/v1/tags"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"name\":\"tag12\",\"description\":\"tag12\"}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/tags");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"name\": \"tag12\"," +
            "\"description\": \"tag12\"" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "name": "tag12",
    "description": "tag12"
}"""
connection.request("POST", "/v1/tags", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""name"": ""tag12"",
            ""description"": ""tag12""
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/tags", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/tags");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'tag12',
    'description' => 'tag12'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/tags',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    name: 'tag12',
    description: 'tag12'
}));
request.end();

Add Tag Response:

200 OK

{
  "id": 19,
  "name": "tag12",
  "description": "tag12",
  "dateCreated": "2017-12-27T13:55:14"
}

This endpoint will add a new tag to your account.

HTTP POST Request

POST https://api.nativemsg.com/v1/tags

POST JSON Payload

Parameter Description
name The name of the Tag. Should be unique for user account.
description The description of the Tag.

The successful creation of a new Tag will return the Tag object below.

POST Tag Response

Parameter Description
id The id of the Tag.
name The name of the Tag. Is unique for user account.
description The description of the Tag.
dateCreated The date and time the Tag was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Update a Tag

Update Tag Request:

curl "https://api.nativemsg.com/v1/tags/19"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X PUT
  -d "{\"name\":\"tag12\",\"description\":\"tag12\"}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPut request = new HttpPut("https://api.nativemsg.com/v1/tags/19");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"name\": \"tag12\"," +
            "\"description\": \"tag12\"" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "name": "tag12",
    "description": "tag12"
}"""
connection.request("PUT", "/v1/tags/19", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""name"": ""tag12"",
            ""description"": ""tag12""
        }";

    var response = await client.PutAsync("https://api.nativemsg.com/v1/tags/19", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/tags/19");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'tag12',
    'description' => 'tag12'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
const request = https.request({
    host: 'api.nativemsg.com',
    path: '/v1/tags/19',
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
});
request.write(JSON.stringify({
    name: 'tag12',
    description: 'tag12'
}));
request.end();

Update Tag Response:

200 OK

{
  "id": 19,
  "name": "tag12",
  "description": "tag12",
  "dateCreated": "2017-12-27T13:55:14"
}

This endpoint will update an existing Tag.

HTTP PUT Request

PUT https://api.nativemsg.com/v1/tags/{tag_id}

PUT JSON Payload

Parameter Description
name The name of the Tag. Should be unique for user account.
description The description of the Tag.

The successful update of a Tag will return the updated Tag object below.

PUT Tag Response

Parameter Description
id The id of the Tag.
name The name of the Tag. Is unique for user account.
description The description of the Tag.
dateCreated The date and time the Tag was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.

Delete a Tag

Delete Tag Request:

curl "https://api.nativemsg.com/v1/tags/19"
  -H "Authorization: Bearer <API_TOKEN>"
  -X DELETE
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpDelete request = new HttpDelete("https://api.nativemsg.com/v1/tags/19");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("DELETE", "/v1/tags/19", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.DeleteAsync("https://api.nativemsg.com/v1/tags/19");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/tags/19");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/tags/19',
    method: 'DELETE',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

Delete Tag Response:

200 OK

{
  "code": 200,
  "message": "Tag #19 was deleted."
}

This endpoint will delete an existing Tag.

HTTP DELETE Request

DELETE https://api.nativemsg.com/v1/tags/{tag_id}

DELETE Tag Response

Parameter Description
code The HTTP status code returned.
message Message about tag deletion result.

Get a List of Humans Assigned to a Tag

HTTP GET Request:

curl "https://api.nativemsg.com/v1/tags/19/humans"
  -H "Authorization: Bearer <API_TOKEN>"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/tags/19/humans");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
connection.request("GET", "/v1/tags/19/humans", headers={"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
    var response = await client.GetAsync("https://api.nativemsg.com/v1/tags/19/humans");
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/tags/19/humans");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https');
https.request({
    host: 'api.nativemsg.com',
    path: '/v1/tags/19/humans',
    headers: {
        Authorization: 'Bearer <API_TOKEN>'
    }
}, response => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => {
        console.log(`Response status code: ${response.statusCode}`);
        console.log(`Response: ${data}`);
    });
}).end();

HTTP GET Response:

200 OK

{
  humanIds: [542, 770]
}

The endpoint will return an array of Human Ids assigned to a tag specified by id.

HTTP GET Request

GET https://api.nativemsg.com/v1/tags/{tag_id}/humans

HTTP GET Response

Parameter Description
humanIds An array of human ids.

Assign a Tag to Humans

Assign a Tag to Humans Request:

curl "https://api.nativemsg.com/v1/tags/19/humans"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{\"humanIds\":[540,770]}"
// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/tags/19/humans");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"humanIds\": [" +
                "540," +
                "770" +
            "]" +
        "}";

    request.setEntity(new StringEntity(payload));

    httpClient.execute(request, response -> {
        System.out.println("Response status code: " + response.getStatusLine().getStatusCode());
        System.out.println("Response: " + EntityUtils.toString(response.getEntity()));
        return null;
    });
}
import http.client
connection = http.client.HTTPSConnection("api.nativemsg.com")
payload = """{
    "humanIds": [
        540,
        770
    ]
}"""
connection.request("POST", "/v1/tags/19/humans", payload, {"Authorization": "Bearer <API_TOKEN>"})
response = connection.getresponse()
print(f"Response status code: {response.status}")
print(f"Response: {response.read().decode('utf-8')}")
// using Microsoft.Net.Http package
using (HttpClient client = new HttpClient()) {
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");

    var payload =
        @"{
            ""humanIds"": [
                540,
                770
            ]
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/tags/19/humans", new StringContent(payload, Encoding.UTF8, "application/json"));
    Console.WriteLine($"Response status code: {(int)response.StatusCode}");
    Console.WriteLine($"Response: {await response.Content.ReadAsStringAsync()}");
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.nativemsg.com/v1/tags/19/humans");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'humanIds' => [
        540,
        770
    ]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer <API_TOKEN>', 'Content-Type: application/json']);
$response = curl_exec($ch);
echo "Response status code: " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . "\n";
echo "Response: " . $response . "\n";
curl_close($ch);
const https = require('https'