NAV
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
dsc Short Code SMS/MMS
dlc Long Code SMS/MMS
fb Facebook
twr Twitter
alx Alexa
web Web Chat
rcs RCS
bmp BMP
tlg Telegram - coming soon
sky Skype - coming soon
slk Slack - coming soon

Supported file types and size limits

Media size limits for DLC channel type

The total message size for DLC channel type must be under 5 MB.

Supported MIME Types for DLC channel type

Audio
Video
Image
Text
Application

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?bot_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?bot_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?bot_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?bot_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?bot_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?bot_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",
    "botId":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 bot id.

HTTP GET Request

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

Get Channels Properties

Parameter Description
bot_id A bot id to filter the channel list. (Optional)

Get Channels List Response

Parameter Description
id The id of the channel
channelType The type of channel (rcs, dlc, web, bmp, etc)
botId The id of the bot 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",
  "botId":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.
botId The id of the bot for this channel.
channelType The type of channel (rcs, dlc, web, bmp, etc)
name The name of the channel. (255 characters max)
description The description of the channel. (200 characters max)
test The flag dermining if the given channel is a test one.
user The public identifier for this channel. (Optional, for Facebook channel only)
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800. (Optional, for Long Code SMS/MMS channel only)
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now. (Optional, for Long Code SMS/MMS channel only)
fallbackId The id of the RCS Emulator used as a fallback message.(Optional, for BMP channel only)
dateCreated The date and time the channel was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
connections The array of connections for the given channel. (Typically contains only one element)

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\",
      \"botId\":1234,
      \"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\"," +
            "\"botId\": 1234," +
            "\"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",
    "botId": 1234,
    "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"",
            ""botId"": 1234,
            ""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',
    'botId' => 1234,
    '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',
    botId: 1234,
    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",
  "botId":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 bot.

HTTP POST Request

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

POST JSON Payload

Parameter Description
channelType The type of channel (rcs, dlc, web, bmp, etc)
botId The id of the bot 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. (Optional, Facebook channel only)
token The password, private key or token for this channel. (Optional, Facebook channel only)
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800. (Optional, Long Code SMS/MMS channel only)
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now.
fallbackId The id of the RCS Emulator used as a fallback message. If it is not specified, fallback messages will be disabled. (Optional, for BMP channel only)
phoneNumber The phone number which is used as a phone number fallback messages should come from. If it is not specified the virtual phone number is acquired from 3rd party service. (Optional, for BMP channel only)
data The arbitrary valid JSON object which contains Verified Sender Setup. (Optional, for RCS and BMP channels only)

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

POST Channel Response

Parameter Description
id The id of the channel.
botId The id of the bot for this channel.
channelType The type of channel (rcs, dlc, web, bmp, etc)
name The name of the channel. (255 characters max)
description The description of the channel. (200 characters max)
test The flag dermining if the given channel is a test one.
user The public identifier for this channel. (Optional, for Facebook channel only)
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800. (Optional, for Long Code SMS/MMS channel only)
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now. (Optional, for Long Code SMS/MMS channel only)
fallbackId The id of the RCS Emulator used as a fallback message. (Optional, for BMP channel only)
dateCreated The date and time the channel was created. Format yyyy-mm-ddThh:mm:ss in GMT 0.
connections The array of connections for the given channel. (Typically contains only one element)

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\",
      \"botId\":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\"," +
            "\"botId\": 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",
    "botId": 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"",
            ""botId"": 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',
    'botId' => 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',
    botId: 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",
  "botId":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
botId The id of the bot for this channel.
name The name of the channel. (255 characters max)
description The description of the channel. (200 characters max)
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now.
fallbackId The id of the RCS Emulator used as a fallback message.(Optional, for BMP channel only)
data The arbitrary valid JSON object which contains Verified Sender Setup. (Optional, for RCS and BMP channels only)

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

PUT Channel Response

Parameter Description
id The id of the channel.
botId The id of the bot for this channel.
channelType The type of channel (rcs, dlc, web, bmp, etc)
name The name of the channel. (255 characters max)
description The description of the channel. (200 characters max)
test The flag dermining if the given channel is a test one.
user The public identifier for this channel. (Optional, for Facebook channel only)
phoneType 1 = user entered non-nativeMsg number, 2 = phone number hosted by nativeMsg, 3 = text enabled #800. (Optional, for Long Code SMS/MMS channel only)
countryCode The country code of a phone number for this channel. US and CA (Canada) are only supported right now (Optional, for Long Code SMS/MMS channel only)
fallbackId The id of the RCS Emulator used as a fallback message.(Optional, for BMP 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.

Get RCS Capability

This endpoint requires only 10-digit long code

RCS Capability Request:

curl "https://api.nativemsg.com/v1/manage/rcs/capability/+12011234567"
  -H "Authorization: Bearer <API_TOKEN>"

// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/manage/rcs/capability/+12011234567");
    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/manage/rcs/capability/+12011234567", 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/manage/rcs/capability/+12011234567");
    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/manage/rcs/capability/+12011234567");
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/manage/rcs/capability/+12011234567',
    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();

RCS Capability Response:

200 OK

{
  "rbmEnabled": true,
  "features": [
    "RICHCARD_STANDALONE",
    "ACTION_CREATE_CALENDAR_EVENT",
    "ACTION_DIAL",
    "ACTION_OPEN_URL",
    "ACTION_SHARE_LOCATION",
    "ACTION_VIEW_LOCATION",
    "RICHCARD_CAROUSEL"
  ],
  "name": null
}

The endpoint will check RCS capability for specified 10-digit long code and return a json-object with available RCS features.

HTTP GET Request

GET https://api.nativemsg.com/v1/manage/rcs/capability/{10DLC}

RCS Capability Response

Parameter Description
rbmEnabled Indicates whether RCS is available for this 10-digit long code or not
features A list of json-strings representing available RCS features
name Field is reserved for future

Get RCS Capability for Specific Channel

This endpoint requires an available RCS channel ID and 10-digit long code

RCS Capability Request:

curl "https://api.nativemsg.com/v1/manage/rcs/capability/12345/+12011234567"
  -H "Authorization: Bearer <API_TOKEN>"

// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/manage/rcs/capability/12345/+12011234567");
    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/manage/rcs/capability/12345/+12011234567", 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/manage/rcs/capability/12345/+12011234567");
    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/manage/rcs/capability/12345/+12011234567");
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/manage/rcs/capability/12345/+12011234567',
    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();

RCS Capability Response:

200 OK

{
  "rbmEnabled": true,
  "features": [
    "RICHCARD_STANDALONE",
    "ACTION_CREATE_CALENDAR_EVENT",
    "ACTION_DIAL",
    "ACTION_OPEN_URL",
    "ACTION_SHARE_LOCATION",
    "ACTION_VIEW_LOCATION",
    "RICHCARD_CAROUSEL"
  ],
  "name": null
}

The endpoint will check RCS capability for specified 10-digit long code and channel ID and return a json-object with available RCS features.

HTTP GET Request

GET https://api.nativemsg.com/v1/manage/rcs/capability/{channel_id}/{10DLC}

RCS Capability Response

Parameter Description
rbmEnabled Indicates whether RCS is abalibale for this 10-digit long code or not
features A list of json-strings representing available RCS features
name Field is reserved for future

Get Phone Number Capabilities

This endpoint lookups specified phone number and returns its capabilities

Phone Number Capabilities Request:

curl "https://api.nativemsg.com/v1/manage/messaging/capability/+12011234567"
  -H "Authorization: Bearer <API_TOKEN>"

// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com//v1/manage/messaging/capability/+12011234567");
    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/manage/messaging/capability/+12011234567", 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/manage/messaging/capability/+12011234567");
    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/manage/messaging/capability/+12011234567");
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/manage/messaging/capability/+12011234567',
    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();

Pnone Number Capabilities Response:

200 OK

{
  "callingCountryCode": "1",
  "countryCode": "US",
  "carrierName": "Verizon Wireless",
  "mobileCountryCode": "310",
  "lineType": "mobile",
  "format": "(201) 123-4567",
  "phoneNumber": "+12011234567",
  "valid": true,
  "validationErrors": []
}

The endpoint lookups passed phone number and retruns a json-object with available common info about its capabilities. Phone number may be passed with or without + sign.

HTTP GET Request

GET https://api.nativemsg.com/v1/manage/messaging/capability/{10DLC}

Phone Number Capabilities Response

Parameter Description
callingCountryCode International dialing prefix of the phone number defined in the E.164 standard
countryCode The phone number's ISO country code
carrierName The name of the carrier
mobileCountryCode The three digit mobile country code of the carrier, used with the mobile network code to identify a mobile network operator
lineType The phone number type. See Type property values Type property values for more information
format The phone number in national format
phoneNumber The phone number in E.164 format, which consists of a + followed by the country code and subscriber number
valid Boolean which indicates if the phone number is in a valid range that can be freely assigned by a carrier to a user
validationErrors Contains reasons why a phone number is invalid. Possible values: TOO_SHORT, TOO_LONG, INVALID_BUT_POSSIBLE, INVALID_COUNTRY_CODE, INVALID_LENGTH, NOT_A_NUMBER

Type Property Values

Carrier data is not available for phone number types: personal, tollFree, premium, sharedCost, uan, voicemail, pager, or unknown. In these cases mobileCountryCode and carrierName values will be null

Type Value Description
landline The phone number is a landline number; generally not capable of receiving SMS messages
mobile The phone number is a mobile number; generally capable of receiving SMS messages
fixedVoip A virtual phone number associated with a physical device (e.g., Comcast or Vonage)
nonFixedVoip A virtual phone number that can be obtained on the internet without the need for a physical device (e.g., Google Voice or Enflick)
personal A phone number designated for personal use.
tollFree A toll-free phone number, which is one where calls are free for the calling party
premium A premium rate phone number, which typically charges higher than normal rates for special services
sharedCost A shared cost phone number, which is one where the charge is partially paid by the calling party and charges higher than normal rates
uan A universal access number, which is a national number which can route incoming calls to different destinations
voicemail A phone number associated with a voicemail service
pager A phone number associated with a pager device
unknown A valid phone number, but the line type could not be determined

Bots

A Bot is a list of rules, logic and messages (Interactions) that processes incoming messages on the Channels associated. A Bot 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 allow to inline data from attributes. For example, if attribute is set to some data then data in message text object {"text": "content of attribute: {attribute}"} is processed to {"text": "content of attribute: some data"}.

Each attribute is defined in particular scope. Scope is usually specified as first part of attribute name followed by colon. There are only five scopes available in the system:

There are special attributes that map to human records:

Following attributes represent current date and time:

If attribute contains valid serialized JSON then its JSON properties can be refered to by specifying path to that properties inside tags using expressions. These expressions support dot and bracket notations and allow to build a path to any value or object inside JSON data. For example, given an attribute root that has JSON-value of two items: [{"id": 10, "text": "first item text"}, {"id": 20, "text": "second item text"}] then its properties can be accessed in tags using the following expressions: "{root[0].id}", "{root[1].text}" and etc.

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:text attribute can be used to access text of current inbound message. If current inbound message doesn't have text or its text is empty then nm:text is set to null.

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.

nm:index attribute exits during the population process and determines an index of current item. After population this attribute is being removed from human records.

<attribute name>:size represents the size of the JSON-array if <attribute name> stores it.

<attribute name>:index represents the index of the last array element in <attribute name> typically represented by takeNext option of Assign Attribute action.

nm:uuid represents random UUID.

nm:function:<function name>[([parameter1,parameter2,...])] represents result of the predefined function <function name> with the given parameters ([parameter1,parameter2,...]). All predefined function are represented in the table given below.

Function name Description Result Example
dateFormat(<datetime>,<dateFormat1>,<dateFormat2>) Converts format of the date-time value stored in <dateTime> attribute from <format1> fromat into <format2>. Represents <dateTime> value in <format2> format or "" if the conversion is not possible. {nm:function:dateFormat(date,yyyy-MM-dd,MM/dd/yyyy)}
embedJson(<sourceJson>,<JSON-path>,<jsonToEmbed>) Gives the JSON value stored in <sourceJson>, finds <JSON-path> in it and embeds there another JSON value stored in <jsonToEmbed>. If <JSON-path< does not exist in <sourceJson> its JSON value will be recustructed to correspond given JSON-path. Represents new JSON value with embedded <jsonToEmbed> in it. If either <sourceJson>, or <jsonToEmbed> can't be considered as valid JSON values or <JSON-path> is invalid function returns "". {nm:function:embed(json1,field.array[1].value,json2)}
uuid Alias of nm:uuid Represents random UUID. nm:function:uuid
evaluate(<expression>) Evaluates passed mathematical expression <expression>. Expression may contain variables represented by attributes names. All variables should contain either constants or other expressions. The result of the evaluation represented by the decimal number with floating point. If expression is invalid or one of its varaibles not found the result is "". {nm:function:evaluate(2 * (x + 1) / 5.25)}
removeField(<json>,<JSON-path>) Removes certain JSON field determined by <JSON-path> from the value of the attribute <json>. Represents new JSON value without removed field. If <JSON-path> does not exist in specified <json> or <json> can't be considered as valid JSON function return <json> without changes. {nm:function:removeField(jsonAttr,field.array[1].value)}

Remark: none of functions has any side-effects such as changed attributes. All attibutes values remain the same.

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 bot 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 which may represent a conditional expression for this action consisting of Condition Objects and Operator Objects applied to them. By default, if none of operators are specified, an array is considered as an expression in which all conditions are obligatory. (Optional)
send A Send Action Object.
dataCapture A Data Capture Action Object
updateAttribute A Update Attribute Action Object. (Deprecated, use Assign Attributes action instead)
assignAttributes An Assign Attributes 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.
updateSettings An Update Settings Object that can update both bot and conversation settings.
validation A Validation Object that is called after execution of the action.

send, waitFor, startDialog, finishDialog, assignTags, subscribe, execute, goto, pause and updateSettings 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.
populate A Populate Object that allows to generate message items based on data from attribute containing JSON. Works for carousel and list messages taking the first item as template.

message, note and rss properties are mutually exclusive. populate is used with message.

Data Capture Action Object Properties

Parameter Description
fields A List of Data Capture Field Objects which will be sent to user. (Required, must not be empty)
displayMode Determines whether this data capture form is madatory or not. Can take 2 values: "message" if form is not requred to be filled up; "popup" if form should be filled up and sent in response message obligatory. (Required, can't be null)
submitButton Name of the button which submits form. (Required, can't be null)
executeOnSubmit Name of the interaction or action which will be triggered once form is submitted. (Optional, by default is null)
dismissButton Name of the button which dismisses form. (Optional, by default is null)
executeOnDismiss Name of the interaction or action which will be triggered once form is dismissed. (Optional, by default is null)
populate A Populate Object that allows to generate fields items based on data from attribute storing JSON.

Data Capture Field Object Properties

Parameter Description
type String property determining a type of this field. Its values are restricted by following once: "text", "select", "checkbox", "radio", "date", "time", "datetime", "switch", "email", "phone". All values are case sensitive, their descriptions are given below. (Required, can't be null)
attribute String property with the name of the attribute which will get the value typed or selected by user. (Required, can't be null)
title String value representing the name of the field. If it's not specified field will not have name. (Optional, by default is null)
placeholder String property determining text of the hint displayed in the field. Used by "text", "date", "time", "datetime", "email", "phone", "select", for other once is ignored. (Optional, by default is null)
required Boolean property which determines whether this field is obligatory to be set by user or not. (Optional, by default is false)
options Property containing json-array of string values. This property is obligatory for "select", "checkbox", "radio" field types, for any other it may be specified but doesn't make any sense. (Required for "select", "checkbox", "radio" field, for other types is ignored)
multi Boolean property which determines whether this field allows to select multiple options. It makes sense only for "select" fields. (Optional, by default is false)

Possible types of data capture fields are given in following table:

Type Description
text Textual field allwing to type certain text.
select Field allowing to select certain options passed in "options" property. Depending upon "multi" state may allow multiple values.
checkbox Similar to select except it always allows to select multiple options.
radio Field allows to select certain option passed in "options" property, but unlike select does not allow to select multiple options.
date Textual field allowing to specify certain date.
time Textual field allowing to specify time date.
datetime Textual field allowing to specify both date and time.
switch Boolean field which value may be true or false.
email Textual field allowing to specify email address.
phone Textual field allowing to specify phone number.

Update Attribute Action Object Properties

(Deprecated. Use Assign Attributes action instead)

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. Also, this property might contain a JSON-array, which will be used when takeNext property is set to true. If it is null then attribute will be removed. (Required)
replace Regular expression which is applied to attribute value to replace matched parts with value. (Optional, by default is not used)
evaluate Specifies whether the value's content should be evaluated or not. Evaluation is done after tags processing. (Optional, default to false)
takeNext Specifies whether the content of the value property should be treated as a JSON-array. If this propery is set to true values from the array will be used to update attribute value (see remark below). (Optional, default is false)
process Specifies whether attributes placeholders in assigning value should be replaced with corresponing values. (Optional, by default is false)
embeddingMode Specifies how attributes placeholders should be treated in values of JSON fields. Has effect only with enabled process option. If this flag is set to true and both assigning value and inserting one can be considered as valid JSON values inserting value is treated as JSON-value and will be embedded into corresponding property. In other cases inserting values will be placed as strings. (Optional, by default is false)

Remark: if value contains JSON-array and takeNext is set to true this action should be in the loop of the Go to action, since during each iteration next value of the array will be used to update attribute value.

Assign Attributes Action Object Properties

Parameter Description
attributes List of Attribute Value Object (Required, must not be empty)
value Default value for all attributes. This is a top-level property. This value will be used if attribite-level property value is not specified. (Optional, by default is null)
evaluate Specifies whether the value's content should be evaluated as an expression or not. Evaluation is done after tags processing. This is a top-level property. This flag will be used if attribute-level evaluate flag is not specified or set to null. (Optional, by default is false)
replace Regular expression which is applied to attribute value to replace matched parts with value. This is a top-level property. This reqular expression will be used if attribute-level replace property is not specified or set to null. (Optional, by default is null)
takeNext Specifies whether the content of the assigning value should be treated as a JSON-array. This is a top-level property. This flag is used if attribute-level takeNext flag is not specified or set to null. If this propery is set to true values from the array will be used to update attribute value, unlike Update Attribute action here this option might be used not only with JSON-arrays but also with JSON-objects. In case of JSON-object the values of its fields will be used as values to assign. (Optional, by default is false)
process Specifies whether attributes placeholders in assigning value should be replaced with corresponing values. This is a top-level property. This flag is used if attribute-level process flag is not specified or set to null. (Optional, by default is false)
embeddingMode Specifies how attributes placeholders should be treated in values of JSON fields. Has effect only with enabled process option. If this flag is set to true and both assigning value and inserting one can be considered as valid JSON values inserting value is treated as JSON-value and will be embedded into corresponding property. In other cases inserting values will be placed as strings. This is a top-level property. This flag is used if attribute-level embeddingMode flag is not specified or set to null. (Optional, by default is false)
remove Specifies that attribute should be removed if it exists. When this flag is set all other options are ignored. This is a top-level property. This flag is used if attribute-level remove flag is not specified or set to null. (Optional, by default is false)

Attribute Value Object Properties

Parameter Description
attributePath A name of the attribute by which the user can access the assigned value. (Required)
value A specific value which will be assigned to this particular attribute. This is an attribute-level property which has higher priority then the same property on top-level. If this field is not specified top-level value is used. (Optional, by default is null)
evaluate Specifies whether the content of this particular attribute should be evaluated as an expression or not. Evaluation is done after tags processing. This is an attribute-level property which has higher priority then the same property on top-level. If this flag is not specified top-level flag is used. (Optional, by default is null)
replace Regular expression which is applied to the value of this particulat attribute to replace matched parts with value. This is an attribute-level property which has higher priority then the same property on top-level. If the regular expression is not specified top-level expression is used. (Optional, by default is null)
takeNext Specifies whether the content of the current assigning value should be treated as a JSON-array. This is an attribute-level property which has higher priority then the same property on top-level. If this flag is not specified top-level flag is used. If this propery is set to true values from the array will be used to update attribute value, unlike Update Attribute action here this option might be used not only with JSON-arrays but also with JSON-objects. In case of JSON-object the values of its fields will be used as values to assign. (Optional, by default is null)
takeNextPath Specifies particular JSON-path in JSON-value which should be used to get the content for takeNext option. If JSON-path is not specified root-node of the JSON-value is used as the content. This property is ignored if takeNext option is not enabled for this attribute. (Optional, by default is null)
process Specifies whether attributes placeholders in the current assigning value should be replaced with the corresponing values. This is an attribute-level property which has higher priority then the same property on top-level. If this flag is not specified top-level flag is used. (Optional, by default is null)
embeddingMode Specifies how attributes placeholders should be treated in values of JSON fields. Has effect only with enabled process option. If this flag is set to true and both assigning value and inserting one can be considered as valid JSON values inserting value is treated as JSON-value and will be embedded into corresponding property. In other cases inserting values will be placed as strings. This is an attribute-level property which has higher priority then the same property on top-level. If this flag is not specified top-level flag is used. (Optional, by default is null)
remove Specifies that current attribute should be removed if it exists. When this flag is set all other options are ignored. (Optional, by default is null)

Wait Action Object Properties

Parameter Description
data Type of the expected data. Can be message or text, quick reply, multi select, number, money, distance, coordinates, datetime, 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)
allowHtml Specifies whether HTML-tags are allowed in response content. (Optional, default to false)
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)
headers An object with all headers need to be passed in request. Property names determine header names. (Optional)
dataFormat The data format of the request content. Can take following values: text, json, form. 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 If value of this field is an attribute name then the whole response is saved into this attribute. Otherwise value of this field treated as template to describe JSON data mapping from response body to attributes in form of {"field": "{value}"} pairs. Each value of those pairs is then saved to the appropriate attribute separately. (Optional)
responseHeaders A name of the attribute where all received response headers will be saved. Headers are stored as JSON-object. (Optional, by default is not used)
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 Long Code SMS/MMS 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)

Populate Object Properties

Parameter Description
from Name of the attribute that contains JSON array. This array will be iterated to fill the data.
attribute Name of the attribute that will be holding current item during iteration of array specified in from property.
allowInnerAttributes Boolean flag which determines whether inner attributes are allowed during populate process. If true all inner placeholders of corresponding attributes if any will also be processed and replaced by corresponding values. (Optional, default value is false)

JsonPath populate

JsonPath provides a mini-language of expressions that might be used in population templates. These expressions refer to a JSON structure stored in an attribute in the same way as XPath expression are used in combination with an XML document. The "root object" in JsonPath is always referred to as $ regardless if it is an object or array. The placeholders for json-path expressions should match following form:

{$<part of expression>}

JsonPath expressions can use the dot–notation

{$.store.products[0].title}

or the bracket–notation

{$['store']['products'][0]['title']}

If expressions are not supposed to be processed and replaced by certain values they can be escaped

\{$<part of expression>}

In this case expression will be treated as a simple text. Remark: In JSON-data \ character should also be escaped to correspond JSON-syntax, thus the client side should pass \\:

"\\{$<part of expression>}"

Syntax of expressions

Syntax of expressions is similar to one used in XPath expressions. All permitted lexemes are given in the table below.

Lexem Description
$ The root element to query. This starts all path expressions.
@ The current node being processed by a filter predicate.
* Wildcard. Available anywhere a name or numeric are required.
.. Deep scan. Available anywhere a name is required. (Use is not recommended.)
['<name>' (, '<name>')] Bracket-notated child or children
[<number> (, <number>)] Array index or indexes
[start:end] Array slice operator. Selects a part of an array from start (inclusive) to end (exclusive)
[?(<expression>)] Filter expression. Expression must evaluate to a boolean value.

Functions

Functions can be invoked at the tail end of a path - the input to a function is the output of the path expression. The function output is dictated by the function itself.

Function Description Output
min() Provides the min value of an array of numbers Real number with floating point
max() Provides the max value of an array of numbers Real number with floating point
avg() Provides the average value of an array of numbers Real number with floating point
stddev() Provides the standard deviation value of an array of numbers Real number with floating point
length() Provides the length of an array Integer number
sum() Provides the sum value of an array of numbers Real number with floating point

Filter expressions

Filters are logical expressions used to filter arrays. A typical filter would be [?(@.price > 20)] where @ represents the current item being processed. More complex filters can be created with logical operators && and ||. String literals must be enclosed by single quotes. (For example: [?(@.color == 'blue')]). Allowed operators which may be used in filter expressions are given below.

Operator Description
== left is equal to right (note that 1 is not equal to '1')
!= left is not equal to right
< left is less than right
<= left is less or equal to right
> left is greater than right
>= left is greater than or equal to right
=~ left matches regular expression [?(@.name =~ /foo.*?/i)]
in left exists in right [?(@.size in ['S', 'M'])]
nin left does not exists in right
subsetof left is a subset of right [?(@.sizes subsetof ['S', 'M', 'L'])]
anyof left has an intersection with right [?(@.sizes anyof ['M', 'L'])]
noneof left has no intersection with right [?(@.sizes noneof ['M', 'L'])]
size size of left (array or string) should match right
empty left (array or string) should be empty

Examples

Assume following JSON-object is stored in an attribute. 

{
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99
            },
            {
                "category": "fiction",
                "author": "Herman Melville",
                "title": "Moby Dick",
                "isbn": "0-553-21311-3",
                "price": 8.99
            },
            {
                "category": "fiction",
                "author": "J. R. R. Tolkien",
                "title": "The Lord of the Rings",
                "isbn": "0-395-19395-8",
                "price": 22.99
            }
        ],
        "bicycle": {
            "color": "red",
            "price": 19.95
        }
    },
    "expensive": 10
}

Expression Result
{$.store.book[*].author} The authors of all books
{$.store..author} All authors
{$.store.*} All things, both books and bicycles
{$.store..price} The price of everything
{$.store.book[2]} The third book
{$.store.book[-2]} The second to last book
{$.store.book[0,1]} The first two books
{$.store.book[:2]} All books from index 0 (inclusive) until index 2 (exclusive)
{$.store.book[1:2]} All books from index 1 (inclusive) until index 2 (exclusive)
{$.store.book[-2:]} Last two books
{$.store.book[2:]} Book number two from tail
{$.store.book[?(@.isbn)]} All books with an ISBN number
{$.store.book[?(@.price < 10)]} All books in store cheaper than 10
{$.store.book[?(@.price <= $['expensive'])]} All books in store that are not "expensive"
{$.store.book[?(@.author =~ /.*REES/i)]} All books matching regex (ignore case)
$..* Give me every thing
$..book.length() The number of books

Remark: Operator .. is not recommended if the root object is not an array or each item also has either an array or an object. Expression parcer will search all the nodes and subnodes to find certain property and in case it is not found it will return null which will be processed as an empty string "". Assume there is following JSON-object: 

[
    {
        "title": "Title 1",
        "subnode": {
            "description": "Description of an item 1",
            "image": "link to an image 1"
        }
    },
    {
        "title": "Title 2",
        "subnode": {
            "description": "Description of an item 2",
            "image": "link to an image 1"
        }
    }
]

In such case an attempt to use expression {$..title} will not return an array ["Title 1", "Title 2"]. The result of the expression will be ["Title 1", null, "Title 2", null] since parcer will search each "subnode" and having not found field title will consider it as null. The same issue concerns {$..description}. Correct way to get all titles is {$[*].title}. For descriptions we should use full path: {$[*].subnode.description}. However if items don't contain any subnodes the results of {$..title} will be correct.

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.

Update Settings Object Properties

Parameter Description
bot An Update Bot Settings Object that describes desired settings of the bot.
conversation An Update Conversation Settings Object that describes desired settings of the conversation.

bot and conversation properties can be used together.

Update Bot Settings Object Properties

Parameter Description
enabled Allows to enable of disable the bot for this conversation. (Optional, default to true)

Update Conversation Settings Object Properties

Parameter Description
priority Sets priority of the conversation. normal and high values are supported right now. (Required)

Condition Object Properties

Parameter Description
channelTypes An array of Channel Types for which this action is suitable. (Optional)
comparisons An array of Comparison Arrays for this condition. (Optional)
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. (Required)
2 The right hand side value of this comparison. (Required)

Comparison operators

Following operators can be applied to numeric values.

Operator Description
"<" (or "less") Evaluates whether left hand side value is less then right hand side one.
"<=" (or "less or equal") Evaluates whether left hand side value is less or equal then right hand side one.
"=" (or "==", "equal") Evaluates whether left hand side value is equal then right hand side one. Also can be applied to string values
"<>" (or "!=", "not equal") Evaluates whether left hand side value is not equal then right hand side one. Also can be applied to string values
">=" (or "greater or equal") Evaluates whether left hand side value is greater or equal then right hand side one.
">" (or "greater") Evaluates whether left hand side value is greater then right hand side one.

Following operator can be applied to an attribute value and one of two right hand side values: present, absent.

Operator Description
is Depending upon right hand side value checks whether attribute contains any value or not.

Following operators can be applied to an attribute value to check it against a regular expression pattern specified as a right hand side value. All operators are case insensitive.

Operator Description
"match" Checks matching of the whole attribute value against the specified pattern.
"notMatch" Checks mismatching of the whole attribute value against the specified pattern.
"entryFound" Checks presence of at least one occurrence within the attribute value which matches the pattern.
"entryNotFound" Checks absence of occurrences within the attribute value which match the pattern.

Following operators can be applied to datetime attributes. Right hand side value should be either numeric or string, or should represent date/time in corresponding format.

Operator Description
"isAfter" (case insensitive alias: "after") Checks if current datetime paramenter is after specified right hand side value.
"isBefore" (case insensitive alias: "before") Checks if current datetime paramenter is before specified right hand side value.
"isInRange" (case insensitive aliases: "inRange", "isOneOf", "oneOf") Checks if current datetime paramenter belongs to range specified in right hand side value. Right hand side value can represent multiple ranges which should be separated by semicolon ;.
"isNotInRange" (case insensitive aliases: "notInRange", "isNotOneOf", "notOneOf") Checks if current datetime paramenter does not belong to range specified in right hand side value. Right hand side value can represent multiple ranges which should be separated by semicolon ;.

Ranges which might be specified in right hand side value can represent either range with start and end value separated by double dots .., or exact value. Date and time should obligatory be represented in corresponding format. (By default in ISO format)

Type of datetime attribute in left hand side value should coinside right hand side value. Required types are given below.

Datetime attribute Type of right hand side value Allowed range of values Example
datetime:date([date format]) String(s) representing date in [date format] format. Indefinite 01/31/2021 (If [date format] is MM/dd/yyyy)
datetime:time([time format]) String(s) representing time in [time format] format. Indefinite 8:00:00 AM (If [time format] is h:mm:ss a)
datetime:datetime([datetime format]) String(s) representing datetime in [datetime format] format. Indefinite 01/31/2021 8:00:00 AM (If [datetime format] is MM/dd/yyyy h:mm:ss a)
datetime:quarterOfYear Integer(s) representing quarter of year. 1..4 1
datetime:year Integer(s) representing year. Indefinite 2021
datetime:monthName([name length option]) String(s) representing name of month. [name length option] can take 3 possible values. Case insensitive. January...December September
datetime:monthNumber Integer(s) representing number of month. 1..12 5
datetime:dayOfYear Integer(s) representing day of year. 1..365(366) 125
datetime:dayOfMonth Integer(s) representing day of month. 1..31 25
datetime:dayOfWeekNumber Integer(s) representing day of week. 1..7 3
datetime:dayOfWeekName([name length option]) String(s) representing day of week name. [name length option] can take 3 possible values. Case insensitive. Monday..Sunday saturday
datetime:weekOfMonth Integer(s) representing week of month. 1..4 2
datetime:weekOfYear Integer(s) representing week of year. 1..52 30
datetime:hour([time convension]) Integer(s) representing hour of day. [time convension] can specify 12-hour or 24-hour convension. If 12-hour format is specified hours are followed with AM/PM suffix. By default 24-hour format is used. 0..23 (for 24-hour convension); 12AM..11PM (for 12-hour convension) 12; 12AM
datetime:minute Integer(s) representing minute of hour. 0..59 25
datetime:second Integer(s) representing second of minute. 0..59 30

Values of [name length option]

Option Description Example
full Full name Monday; September
short Name abbriviation. Typically of 3 letters. Mon; Sep
narrow Narrow name of 1 letter.(not recommended since several names can start from one and the same letter: Saturday, Sunday) M; S

Operator Object Properties

An object represents logical operator which should be applied to conditions.

Parameter Description
operator A string representing logical operator. (Required)

Supports following operators:

Sequences and, or, not are case insensitive.

Example of logical expression:

"conditions": [
    {
        "operator": "not"
    },
    {
        "channelTypes": [],
        "comparisons": [
            [
                "answer",
                "equal",
                "one"
            ]
        ]
    },
    {
        "operator": "and"
    },
    {
        "operator": "not"
    },
    {
        "channelTypes": [],
        "comparisons": [
            [
                "answer",
                "equal",
                "two"
            ]
        ]
    }
]

An array of conditions shown above will be treated as logical expression "not comparsion1 and not comparsion2" where comparsion1 is

{
    "channelTypes": [],
    "comparisons": [
        [
            "answer",
            "equal",
            "one"
        ]
    ]
}

and comparsion2 is

{
    "channelTypes": [],
    "comparisons": [
        [
            "answer",
            "equal",
            "two"
        ]
    ]
}

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"
  -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 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 bot\",
      \"interactions\": [
        {
          \"name\": \"Interaction #1\",
          \"intents\": [
            \"send response\"
          ],
          \"actions\": [
            {
              \"send\": {
                \"message\": {
                  \"text\": \"example response\"
                }
              },
              \"type\": \"Text\",
              \"name\": \"action #1\"
            }
          ]
        },
        {
          \"pos\": {
            \"top\": 100
          },
          \"name\": \"Interaction #2\",
          \"intents\": [
            \"enter text\"
          ],
          \"actions\": [
            {
              \"send\": {
                \"message\": {
                  \"text\": \"please enter some text\"
                }
              },
              \"type\": \"Text\",
              \"name\": \"action #2\"
            },
            {
              \"waitFor\": {
                \"content\": \"someText\",
                \"data\": [
                  \"message\"
                ]
              },
              \"type\": \"Wait For\",
              \"conditions\": [],
              \"name\": \"action #3\"
            },
            {
              \"send\": {
                \"message\": {
                  \"text\": \"thank you for entering {someText}\"
                }
              },
              \"type\": \"Text\",
              \"name\": \"action #4\"
            }
          ]
        }
      ]
    }"

// 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 = "{\n" +
            "  \"name\": \"Example bot\",\n" +
            "  \"interactions\": [\n" +
            "    {\n" +
            "      \"name\": \"Interaction #1\",\n" +
            "      \"intents\": [\n" +
            "        \"send response\"\n" +
            "      ],\n" +
            "      \"actions\": [\n" +
            "        {\n" +
            "          \"send\": {\n" +
            "            \"message\": {\n" +
            "              \"text\": \"example response\"\n" +
            "            }\n" +
            "          },\n" +
            "          \"type\": \"Text\",\n" +
            "          \"name\": \"action #1\"\n" +
            "        }\n" +
            "      ]\n" +
            "    },\n" +
            "    {\n" +
            "      \"pos\": {\n" +
            "        \"top\": 100\n" +
            "      },\n" +
            "      \"name\": \"Interaction #2\",\n" +
            "      \"intents\": [\n" +
            "        \"enter text\"\n" +
            "      ],\n" +
            "      \"actions\": [\n" +
            "        {\n" +
            "          \"send\": {\n" +
            "            \"message\": {\n" +
            "              \"text\": \"please enter some text\"\n" +
            "            }\n" +
            "          },\n" +
            "          \"type\": \"Text\",\n" +
            "          \"name\": \"action #2\"\n" +
            "        },\n" +
            "        {\n" +
            "          \"waitFor\": {\n" +
            "            \"content\": \"someText\",\n" +
            "            \"data\": [\n" +
            "              \"message\"\n" +
            "            ]\n" +
            "          },\n" +
            "          \"type\": \"Wait For\",\n" +
            "          \"conditions\": [],\n" +
            "          \"name\": \"action #3\"\n" +
            "        },\n" +
            "        {\n" +
            "          \"send\": {\n" +
            "            \"message\": {\n" +
            "              \"text\": \"thank you for entering {someText}\"\n" +
            "            }\n" +
            "          },\n" +
            "          \"type\": \"Text\",\n" +
            "          \"name\": \"action #4\"\n" +
            "        }\n" +
            "      ]\n" +
            "    }\n" +
            "  ]\n" +
            "}";

    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 bot",
  "interactions": [
    {
      "name": "Interaction #1",
      "intents": [
        "send response"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "example response"
            }
          },
          "type": "Text",
          "name": "action #1"
        }
      ]
    },
    {
      "pos": {
        "top": 100
      },
      "name": "Interaction #2",
      "intents": [
        "enter text"
      ],
      "actions": [
        {
          "send": {
            "message": {
              "text": "please enter some text"
            }
          },
          "type": "Text",
          "name": "action #2"
        },
        {
          "waitFor": {
            "content": "someText",
            "data": [
              "message"
            ]
          },
          "type": "Wait For",
          "conditions": [],
          "name": "action #3"
        },
        {
          "send": {
            "message": {
              "text": "thank you for entering {someText}"
            }
          },
          "type": "Text",
          "name": "action #4"
        }
      ]
    }
  ]
}"""
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 bot"",
      ""interactions"": [
        {
          ""name"": ""Interaction #1"",
          ""intents"": [
        ""send response""
          ],
          ""actions"": [
        {
          ""send"": {
            ""message"": {
              ""text"": ""example response""
            }
          },
          ""type"": ""Text"",
          ""name"": ""action #1""
        }
          ]
        },
        {
          ""pos"": {
        ""top"": 100
          },
          ""name"": ""Interaction #2"",
          ""intents"": [
        ""enter text""
          ],
          ""actions"": [
        {
          ""send"": {
            ""message"": {
              ""text"": ""please enter some text""
            }
          },
          ""type"": ""Text"",
          ""name"": ""action #2""
        },
        {
          ""waitFor"": {
            ""content"": ""someText"",
            ""data"": [
              ""message""
            ]
          },
          ""type"": ""Wait For"",
          ""conditions"": [],
          ""name"": ""action #3""
        },
        {
          ""send"": {
            ""message"": {
              ""text"": ""thank you for entering {someText}""
            }
          },
          ""type"": ""Text"",
          ""name"": ""action #4""
        }
          ]
        }
      ]
    }";

    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 A valid json-array of the Interaction Objects. If an empty array is passed, a bot is created without interactions. 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 A valid json-array of the Interaction Objects. If an empty array is passed, all interactions of the bot will be removed if any. Required

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 An Id of the bot revision.
botId An Id of the bot.
revision A revision number.
revisionName A name of the represented revision.
name A name of the bot (100 characters max).
data An array of the Interaction Objects of the represented revision.

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,
  "revisionName": "v0.100 interaction modification",
  "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/bots/{bot_id}/revisions/{revision}

GET Bot Revision Response

Parameter Description
id An Id of the represented revision.
botId An Id for the bot.
revision A revision number.
revisionName A name of the represented revision.
name A name of the bot. (100 characters max)
welcomeMessageExecute A name of the bot interaction executed to display an invitation start message.
data An array of the Interaction Objects of the represented revision.

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."
          }
        }
      }
    ]
  }
]

Assigns Tags to a Human

Example shows actions that assign single or several 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": 542,
  "botId": 451,
  "botName": "Test Bot",
  "botEnabled": true,
  "handles": [
      "Linked Human Name 1",
      "Linked Human Name 2"
  ],
  "name": "Chris Chiovare",
  "firstName": "Chris",
  "lastName": "Chiovare",
  "gender": "M",
  "company": "SkyLine",
  "email": "chrischiovare@mail.com",
  "phoneNumber": "+12223334455",
  "mobileCarrier": "Verizon",
  "timezone": 3,
  "profilePic": "https://example.com/pictureOfMe.jpg",
  "dateCreated": "2017-07-03T16:08:48",
  "locale": "en_US",
  "channels": [{
    "lastCommunication": "2019-10-02T12:08:02",
    "id": 551,
    "type": "fb",
    "lastSubscription": "2017-07-03T16:08:48"
  }],
  "subscribedChannels": [{
    "lastCommunication": "2019-10-02T12:08:02",
    "id": 551,
    "type": "fb",
    "lastSubscription": "2017-07-03T16:08:48"
  }],
  "customFields": {
    "page": "10",
    "option": "2",
    "custom": "value"
  },
  "fbSettings": {
    "plusOne": true,
    "optinDate": "2017-12-08T16:05:24"
  },
  "rcsEnabled": true,
  "rcsFeatures": [
      "RICHCARD_STANDALONE",
      "ACTION_CREATE_CALENDAR_EVENT",
      "ACTION_DIAL",
      "ACTION_OPEN_URL",
      "ACTION_SHARE_LOCATION",
      "ACTION_VIEW_LOCATION",
      "RICHCARD_CAROUSEL",
      "PAYMENTS_V1"
  ]
}]

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
botId The id of the Bot connected to the Human
botName The name of the Bot connected to the Human
botEnabled Indicates whether a bot is enabled for this human or not.
handles Array of linked humans names.
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
company The company name of the Human.
email Email address of the Human.
phoneNumber The phone number of the Human.
mobileCarrier The mobile carrier of the Human.
timezone The integer value +/- from GMT 0.
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.
locale The locale of the user. Example en_US.
channels The list of channels the human belongs to.
    id The id of the channel.
    type The type of the channel.
    lastCommunication The date and time when the Human had last communication with the Bot or User. Format yyyy-mm-ddThh:mm:ss in GMT 0.
    lastSubscription The date and time when the Human had last subscription to the channel. Format yyyy-mm-ddThh:mm:ss in GMT 0.
subscribedChannels The list of channels the human subscribed to.
customFields Object with all custom fields that are set during the conversation.
fbSettings Facebook specific settings of the Human.
rcsEnabled Indicates whether RCS is enabled for the Human.
rcsFeatures List of RCS features supported by the Human.

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": 542,
  "botId": 451,
  "botName": "Test Bot",
  "botEnabled": true,
  "handles": [
      "Linked Human Name 1",
      "Linked Human Name 2"
  ],
  "name": "Chris Chiovare",
  "firstName": "Chris",
  "lastName": "Chiovare",
  "gender": "M",
  "company": "SkyLine",
  "email": "chrischiovare@mail.com",
  "phoneNumber": "+12223334455",
  "mobileCarrier": "Verizon",
  "timezone": 3,
  "profilePic": "https://example.com/pictureOfMe.jpg",
  "dateCreated": "2017-07-03T16:08:48",
  "locale": "en_US",
  "channels": [{
    "lastCommunication": "2019-10-02T12:08:02",
    "id": 551,
    "type": "fb",
    "lastSubscription": "2017-07-03T16:08:48"
  }],
  "subscribedChannels": [{
    "lastCommunication": "2019-10-02T12:08:02",
    "id": 551,
    "type": "fb",
    "lastSubscription": "2017-07-03T16:08:48"
  }],
  "customFields": {
    "page": "10",
    "option": "2",
    "custom": "value"
  },
  "fbSettings": {
    "plusOne": true,
    "optinDate": "2017-12-08T16:05:24"
  },
  "rcsEnabled": true,
  "rcsFeatures": [
      "RICHCARD_STANDALONE",
      "ACTION_CREATE_CALENDAR_EVENT",
      "ACTION_DIAL",
      "ACTION_OPEN_URL",
      "ACTION_SHARE_LOCATION",
      "ACTION_VIEW_LOCATION",
      "RICHCARD_CAROUSEL",
      "PAYMENTS_V1"
  ]
}

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
botId The id of the Bot connected to the Human
botName The name of the Bot connected to the Human
botEnabled Indicates whether a bot is enabled for this human or not.
handles Array of linked humans names.
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
company The company name of the Human.
email Email address of the Human.
phoneNumber The phone number of the Human.
mobileCarrier The mobile carrier of the Human.
timezone The integer value +/- from GMT 0.
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.
locale The locale of the user. Example en_US.
channels The list of channels the human belongs to.
    id The id of the channel.
    type The type of the channel.
    lastCommunication The date and time when the Human had last communication with the Bot or User. Format yyyy-mm-ddThh:mm:ss in GMT 0.
    lastSubscription The date and time when the Human had last subscription to the channel. Format yyyy-mm-ddThh:mm:ss in GMT 0.
subscribedChannels The list of channels the human subscribed to.
customFields Object with all custom fields that are set during the conversation.
fbSettings Facebook specific settings of the Human.
rcsEnabled Indicates whether RCS is enabled for the Human.
rcsFeatures List of RCS features supported by the Human.

Find humans by their attributes

List of humans with attribute "attribute1" specified. Request:

curl "https://api.nativemsg.com/v1/humans?filters=%5B%7B%22type%22%3A%22ATTRIBUTE%22%2C%22value%22%3A%5B%7B%22attributeName%22%3A%22attribute1%22%2C%22operator%22%3A%22present%22%7D%5D%7D%5D"
  -H "Authorization: Bearer <API_TOKEN>"

// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpGet request = new HttpGet("https://api.nativemsg.com/v1/humans?filters=%5B%7B%22type%22%3A%22ATTRIBUTE%22%2C%22value%22%3A%5B%7B%22attributeName%22%3A%22attribute1%22%2C%22operator%22%3A%22present%22%7D%5D%7D%5D");
    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?filters=%5B%7B%22type%22%3A%22ATTRIBUTE%22%2C%22value%22%3A%5B%7B%22attributeName%22%3A%22attribute1%22%2C%22operator%22%3A%22present%22%7D%5D%7D%5D", 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?filters=%5B%7B%22type%22%3A%22ATTRIBUTE%22%2C%22value%22%3A%5B%7B%22attributeName%22%3A%22attribute1%22%2C%22operator%22%3A%22present%22%7D%5D%7D%5D");
    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?filters=%5B%7B%22type%22%3A%22ATTRIBUTE%22%2C%22value%22%3A%5B%7B%22attributeName%22%3A%22attribute1%22%2C%22operator%22%3A%22present%22%7D%5D%7D%5D");
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?filters=%5B%7B%22type%22%3A%22ATTRIBUTE%22%2C%22value%22%3A%5B%7B%22attributeName%22%3A%22attribute1%22%2C%22operator%22%3A%22present%22%7D%5D%7D%5D',
    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 humans with attribute "attribute1" specified. Response:

200 OK

[
    {
        "id": 123456,
        "name": "Test human",
        "firstName": "Chris",
        "lastName": "Chiovare",
        "gender": "M",
        "company": "SkyLine",
        "email": "chrischiovare@mail.com",
        "phoneNumber": "+12223334455",
        "mobileCarrier": "Verizon",
        "timezone": 3,
        "profilePic": "https://example.com/pictureOfMe.jpg",
        "dateCreated": "2021-07-22T16:08:48",
        "locale": "en_US",
        "channels": [
            {
                "id": 1234,
                "type": "web",
                "lastCommunication": "2021-07-02T13:34:52Z",
                "lastSubscription": "2021-07-06T08:52:50.656339Z"
            }
        ],
        "customFields": {
            "nm:lastInteraction": "Interaction #1",
            "attribute1": "test value",
        },
        "botId": 5678,
        "botName": "Test bot",
        "botEnabled": true,
        "handles": null,
        "rcsEnabled": true,
        "rcsFeatures": [
            "RICHCARD_STANDALONE",
            "ACTION_CREATE_CALENDAR_EVENT",
            "ACTION_DIAL",
            "ACTION_OPEN_URL",
            "ACTION_SHARE_LOCATION",
            "ACTION_VIEW_LOCATION",
            "RICHCARD_CAROUSEL",
            "PAYMENTS_V1"
        ],
        "loaded": false,
        "subscribedChannels": [
            {
                "id": 1234,
                "type": "web",
                "lastCommunication": "2021-07-02T13:34:52Z",
                "lastSubscription": "2021-07-06T08:52:50.656339Z"
            }
        ],
        "fbSettings": {
            "plusOne": true,
            "optinDate": "2017-12-08T16:05:24"
        },
        "messageStatus": null,
        "isConversationDeleted": false,
        "status": "enabled",
        "test": false
    }
]

The endpoint will return an array of humans with attribute named "attribute1" specified.

HTTP GET Request

GET https://api.nativemsg.com/v1/humans?filters={filter}

The value {filter} should represent a url-encoded JSON-object of following structure:

[{"type":"ATTRIBUTE","value":[{"attributeName":"attribute1","operator":"present"}]}]

Each object of the "value" array should contain following fields:

Field name Description
attributeName A name of the attribute to look for
operator an operator to be applied to the value of the attribute (operators are given below)
value string value against which an actual attribute value will be estimated (not necessary for "absent" and "present" operators)

Available operators:

Operator name Description
present Finds humans which have attributeName attribute.
absent Finds humans which don't have attributeName attribute.
equal finds humans with attributeName attribute which value is equal value. May be applied to string and numeric attributes.
notEqual Finds humans with attributeName attribute which value is not equal value. May be applied to string and numeric attributes.
greater Finds humans with attributeName attribute which value is greater then value. May be applied to numeric attributes.
greaterOrEqual Finds humans with attributeName attribute which value is greater or equal value. May be applied to numeric attributes.
less Finds humans with attributeName attribute which value is less then value. May be applied to numeric attributes.
lessOrEqual Finds humans with attributeName attribute which value is less or equal value. May be applied to numeric attributes.

All inconsistencies are estimated as false. For instance, if the user looks for humans with attr2 attribute greater or equal then 102, none of humans which have this attribute specified but with the text value will be found. The same with operator notEqual. This operator finds only those humans who have this attribute and its value not equal specified value and doesn't find humans without this attribute at all. Conditions in one and the same filter are combined with OR logical operator.

Get Human Response

Parameter Description
id The id of the Human
botId The id of the Bot connected to the Human
botName The name of the Bot connected to the Human
botEnabled Indicates whether a bot is enabled for this human or not.
handles Array of linked humans names.
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
company The company name of the Human.
email Email address of the Human.
phoneNumber The phone number of the Human.
mobileCarrier The mobile carrier of the Human.
timezone The integer value +/- from GMT 0.
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.
locale The locale of the user. Example en_US.
channels The list of channels the human belongs to.
    id The id of the channel.
    type The type of the channel.
    lastCommunication The date and time when the Human had last communication with the Bot or User. Format yyyy-mm-ddThh:mm:ss in GMT 0.
    lastSubscription The date and time when the Human had last subscription to the channel. Format yyyy-mm-ddThh:mm:ss in GMT 0.
subscribedChannels The list of channels the human subscribed to.
customFields Object with all custom fields that are set during the conversation.
fbSettings Facebook specific settings of the Human.
rcsEnabled Indicates whether RCS is enabled for the Human.
rcsFeatures List of RCS features supported by the Human.
messageStatus Status of the message.
isConversationDeleted" Determines whether conversation was deleted.
status Status of the human determining whether it was deleted (disabled) or not (enabled).
test Determines whether this human is test one.

Enable/Disable Human's Bot

Enable/Disable Humans's Bot 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\": true" +
        "}";

    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": true
}"""
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"": true
        }";

    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' => true
]));
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: true
}));
request.end();

Enable/Disable Human's Bot Response:

200 OK

{
  "id": 542,
  "botId": 451,
  "botName": "Test Bot",
  "botEnabled": true,
  "handles": [
      "Linked Human Name 1",
      "Linked Human Name 2"
  ],
  "name": "Chris Chiovare",
  "firstName": "Chris",
  "lastName": "Chiovare",
  "gender": "M",
  "company": "SkyLine",
  "email": "chrischiovare@mail.com",
  "phoneNumber": "+12223334455",
  "mobileCarrier": "Verizon",
  "timezone": 3,
  "profilePic": "https://example.com/pictureOfMe.jpg",
  "dateCreated": "2017-07-03T16:08:48",
  "locale": "en_US",
  "channels": [{
    "lastCommunication": "2019-10-02T12:08:02",
    "id": 551,
    "type": "fb",
    "lastSubscription": "2017-07-03T16:08:48"
  }],
  "subscribedChannels": [{
    "lastCommunication": "2019-10-02T12:08:02",
    "id": 551,
    "type": "fb",
    "lastSubscription": "2017-07-03T16:08:48"
  }],
  "customFields": {
    "page": "10",
    "option": "2",
    "custom": "value"
  },
  "fbSettings": {
    "plusOne": true,
    "optinDate": "2017-12-08T16:05:24"
  },
  "rcsEnabled": true,
  "rcsFeatures": [
      "RICHCARD_STANDALONE",
      "ACTION_CREATE_CALENDAR_EVENT",
      "ACTION_DIAL",
      "ACTION_OPEN_URL",
      "ACTION_SHARE_LOCATION",
      "ACTION_VIEW_LOCATION",
      "RICHCARD_CAROUSEL",
      "PAYMENTS_V1"
  ]
}

This endpoint will enable or disable a bot for the human specified by its ID.

HTTP PUT Request

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

PUT JSON Payload

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

PUT Human Response

Parameter Description
id The id of the Human
botId The id of the Bot connected to the Human
botName The name of the Bot connected to the Human
botEnabled Indicates whether a flow's bot is enabled for this human or not.
handles Array of linked humans names.
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
company The company name of the Human.
email Email address of the Human.
phoneNumber The phone number of the Human.
mobileCarrier The mobile carrier of the Human.
timezone The integer value +/- from GMT 0.
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.
locale The locale of the user. Example en_US.
channels The list of channels the human belongs to.
    id The id of the channel.
    type The type of the channel.
    lastCommunication The date and time when the Human had last communication with the Bot or User. Format yyyy-mm-ddThh:mm:ss in GMT 0.
    lastSubscription The date and time when the Human had last subscription to the channel. Format yyyy-mm-ddThh:mm:ss in GMT 0.
subscribedChannels The list of channels the human subscribed to.
customFields Object with all custom fields that are set during the conversation.
fbSettings Facebook specific settings of the Human.
rcsEnabled Indicates whether RCS is enabled for the Human.
rcsFeatures List of RCS features supported by the Human.

Add Humans by phones

Add Humans by Phones Request:

curl "https://api.nativemsg.com/v1/channels/121222/add_humans"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X POST
  -d "{
    \"humans\": [
        {
            \"firstName\": \"John\",
            \"lastName\": \"Rambo\",
            \"userName\": \"john_rambo\",
            \"company\": \"John Rambo & Co\",
            \"phone\": \"12223334455\",
            \"customFields\": {
                \"attributeName1\": \"attribute value 1\",
                \"attributeName2\": \"attribute value 2\"
            }
        }, {
            \"firstName\": \"Sarah\",
            \"lastName\": \"Connor\",
            \"userName\": \"sarah_connor\",
            \"company\": \"Sarah Connor & Co\",
            \"phone\": \"12223334456\",
            \"customFields\": {
                \"attributeName1\": \"attribute value 1\",
                \"attributeName2\": \"attribute value 2\"
            }
        }
    ],
    \"assignTags\": [
        1234, 5678
    ],
    \"subscribe\": true,
    \"updateExisting\": true
}"

// using Apache HTTP Components
try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
    HttpPost request = new HttpPost("https://api.nativemsg.com/v1/channels/121222/add_humans");
    request.setHeader("Authorization", "Bearer <API_TOKEN>");
    request.setHeader("Content-Type", "application/json");

    String payload =
        "{" +
            "\"humans\": [" +
                "{" +
                    "\"firstName\": \"John\"," +
                    "\"lastName\": \"Rambo\"," +
                    "\"userName\": \"john_rambo\"," +
                    "\"company\": \"John Rambo & Co\"," +
                    "\"phone\": \"12223334455\"," +
                    "\"customFields\": {" +
                        "\"attributeName1\": \"attribute value 1\"," +
                        "\"attributeName2\": \"attribute value 2\"" +
                    "}" +
                "}," +
                "{" +
                    "\"firstName\": \"Sarah\"," +
                    "\"lastName\": \"Connor\"," +
                    "\"userName\": \"sarah_connor\"," +
                    "\"company\": \"Sarah Connor & Co\"," +
                    "\"phone\": \"12223334456\"," +
                    "\"customFields\": {" +
                        "\"attributeName1\": \"attribute value 1\"," +
                        "\"attributeName2\": \"attribute value 2\"" +
                    "}" +
                "}" +
            "]," +
            "\"assignTags\": [" +
                "1234," +
                "5678" +
            "]," +
            "\"subscribe\": true," +
            "\"updateExisting\": true" +
        "}";

    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 = """{
    "humans": [
        {
            "firstName": "John",
            "lastName": "Rambo",
            "userName": "john_rambo",
            "company": "John Rambo & Co",
            "phone": "12223334455",
            "customFields": {
                "attributeName1": "attribute value 1",
                "attributeName2": "attribute value 2"
            }
        },
        {
            "firstName": "Sarah",
            "lastName": "Connor",
            "userName": "sarah_connor",
            "company": "Sarah Connor & Co",
            "phone": "12223334456",
            "customFields": {
                "attributeName1": "attribute value 1",
                "attributeName2": "attribute value 2"
            }
        }
    ],
    "assignTags": [
        1234,
        5678
    ],
    "subscribe": true,
    "updateExisting": true
}"""
connection.request("POST", "/v1/channels/121222/add_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 =
        @"{
            ""humans"": [
                {
                    ""firstName"": ""John"",
                    ""lastName"": ""Rambo"",
                    ""userName"": ""john_rambo"",
                    ""company"": ""John Rambo & Co"",
                    ""phone"": ""12223334455"",
                    ""customFields"": {
                        ""attributeName1"": ""attribute value 1"",
                        ""attributeName2"": ""attribute value 2""
                    }
                },
                {
                    ""firstName"": ""Sarah"",
                    ""lastName"": ""Connor"",
                    ""userName"": ""sarah_connor"",
                    ""company"": ""Sarah Connor & Co"",
                    ""phone"": ""12223334456"",
                    ""customFields"": {
                        ""attributeName1"": ""attribute value 1"",
                        ""attributeName2"": ""attribute value 2""
                    }
                }
            ],
            ""assignTags"": [
                1234,
                5678
            ],
            ""subscribe"": true,
            ""updateExisting"": true
        }";

    var response = await client.PostAsync("https://api.nativemsg.com/v1/channels/121222/add_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/channels/121222/add_humans");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'humans' => [
        {
            'firstName' => 'John',
            'lastName' => 'Rambo',
            'userName' => 'john_rambo',
            'company' => 'John Rambo & Co',
            'phone' => '12223334455',
            'customFields' => {
                'attributeName1' => 'attribute value 1',
                'attributeName2' => 'attribute value 2'
            }
        ],
        {
            'firstName' => 'Sarah',
            'lastName' => 'Connor',
            'userName' => 'sarah_connor',
            'company' => 'Sarah Connor & Co',
            'phone' => '12223334456',
            'customFields' => {
                'attributeName1' => 'attribute value 1',
                'attributeName2' => 'attribute value 2'
            }
        }
    ],
    'assignTags' => [
        1234,
        5678
    ],
    'subscribe' => true,
    'updateExisting' => true
}));
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/add_humans',
    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({
    humans: [
        {
            firstName: 'John',
            lastName: 'Rambo',
            userName: 'john_rambo',
            company: 'John Rambo & Co',
            phone: '12223334455',
            customFields: {
                attributeName1: 'attribute value 1',
                attributeName2: 'attribute value 2'
            }
        },
        {
            firstName: 'Sarah',
            lastName: 'Connor',
            userName: 'sarah_connor',
            company: 'Sarah Connor & Co',
            phone: '12223334456',
            customFields: {
                attributeName1: 'attribute value 1',
                attributeName2: 'attribute value 2'
            }
        }
    ],
    assignTags: [
        1234,
        5678
    ],
    subscribe: true,
    updateExisting: true
}));
request.end();

Add Humans by Phones Response:

200 OK

{
  "code": 200,
  "message": "Humans [123456, 123457] were successfully added and subscribed to channel 121222 and assigned to tags [1234, 5678]."
}

This endpoint will add new or update existing humans by provided phone numbers.

HTTP POST Request

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

POST JSON Payload

Parameter Description
humans An array of Human by Phone Objects. (Required)
assignTags An array of tag ids or tag names. (Optional)
If active tag with that name not found, it will be created.
subscribe Indicates whether a human should be subscribed to the channel. (Optional)
updateExisting Indicates whether existing human should be updated with provided info. (Optional)
If human with specified phone already exists and value is:
   â€˘ true - it will be updated with additionally provided info;
   â€˘ false or not specified - it won't be updated.

Human by Phone Object Properties

Parameter Description
firstName The first name of the Human. (Optional)
lastName The last name of the Human. (Optional)
userName The user name of the Human. (Optional)
company The company name of the Human. (Optional)
phone The phone number of the Human. (Required)
customFields The arbitrary JSON object containing custom attributes of the Human where field name is an attribute name and field value is an attribute value. (Optional)

HTTP POST Response

Parameter Description
code The HTTP status code returned
message Message describing adding new humans result.

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

{
    "channelId": 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.

HTTP POST 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

{
    "channelId": 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

{
    "channelId": 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.

Add or update human attributes

Add Human custom attributes:

curl "https://api.nativemsg.com/v1/humans/123/attributes"
  -H "Authorization: Bearer <API_TOKEN>"
  -H "Content-Type: application/json"
  -X PUT
  -d "{
        \"attributeName\": \"attribute value\",
      }"

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

    String payload =
        "{" +
            "\"attributeName\": \"attribute value\"" +
        "}";

    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 = """{
    "attributeName": "attribute value"
}"""

connection.request("PUT", "/v1/humans/123/attributes", 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 =
        @"{
            ""attributeName"": ""attribute value""
        }";

    var response = await client.PutAsync("https://api.nativemsg.com/v1/humans/123/attributes", 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/123/attributes");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'attributeName' => 'attribute value'
]));
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/123/attributes',
    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({
    attributeName: "attribute value"
}));
request.end();

Add Human custom attributes Response:

200 OK

{
    "attributeName": "attribute value"
}

This endpoint will add new or update existing custom attributes of the provided human.

HTTP PUT Request

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

PUT JSON Payload

Parameter Description
represents name of the attribute represents value of this attribute (Required)

Payload may containt arbitrary amount of attributes

HTTP PUT Response

Parameter Description
represents name of the attribute represents value of this attribute

Other fields of the response represent other existing attributes if any

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
title The title of the message - 200 characters max.
text The text of the message - 1600 characters max.
mediaType "text", "image", "audio", video", "file".
media The full URL of the media content (image, video, audio or file). In case of RCS channel type a media file will be cached for 30 days; after the specified period in case of the message resending the system will download the media file from remote resource again. Supported types of media in RCS channel are image and video.
targets An array of Target Objects of recipients.
buttons An array of Button Objects. In case of RCS channel type buttons are supported for standalone Rich Card and carousel Card item.
quickReplies An array of Quick Reply Objects. In case of RCS channel type quick replies can be attached outside of standalone or carousel rich cards, text or media message.
carousel An array of Carousel Objects. In case of RCS channel type a message will be sent in a form of carousel of Rich Cards with vertical layout.
list An array of List Objects.
richCard A Rich Card Object. Supported by RCS channel type. In case if specified along with title, media or text a message will be sent in a form of a standalone Rich Card. Also can be specified along with carousel. In case if specified as empty object {} default values are applied. optional
populateQuickReplies A Populate Object that allows to generate Quick Reply Objects items based on data from attribute containing JSON.
populateButtons A Populate Object that allows to generate Button Objects items based on data from attribute containing JSON.

In case of RCS channel type one of text, media or richCard option is required. In case if richCard is specified, one of media or title is required.

Target Object Properties

Parameter Description
targetType Value can be "humans", "channels", "tags", "phones".
ids An array of the targetType ids. For humans, channels and tags target types.
phones An array of the phone numbers. For phones target type.
channelId An id of a channel in which message sending should be performed. For phones target type.
subscription A boolean value. When set to true message sending will proceed for humans subscribed to their channel only.

Button and Quick Reply Object Properties

Parameter Description
type The type of button or reply. The various types supported per channel are shown in the table below, required
title The text of the button or reply. Maximum title length per channel is shown in the table below, required
payload The value for the pressed button or quick reply 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. for type "postback", required
execute The name of the interaction/action that will be executed when this button or quick reply is pressed. for type "postback", optional
imageUrl The URL of the image for text replies. quick reply only, optional
query The address of location. for type "viewLocation", one of "query" or "latLong" required
latLong The coordinates of location in the form {"latitude": number, "longitude": number}. for type "viewLocation", one of "query" or "latLong" required
label The name of location when it is specified using "latLong". for type "viewLocation", optional
startTime The start date and time of an event in the form 2019-02-12T15:01:23.045123456Z. for type "calendar", required
endTime The end date and time of an event in the form 2019-02-12T15:01:23.045123456Z. for type "calendar", required
eventTitle The title of an event. for type "calendar", required
description The description of an event. for type "calendar", optional

Button and Quick Reply count limits per channel are shown at the table below.

Types of Button and Quick Reply objects

Channel FB TW WEB RCS
Type BTN QR BTN QR BTN QR BTN QR
weburl âś” âś” âś” âś” âś” âś”
call âś” âś” âś” âś” âś”
postback âś” âś” âś” âś” âś” âś” âś”
location âś” âś” âś”
viewLocation âś” âś”
calendar âś” âś”
share âś”
defaultAction âś” âś”
Max count 3 11 3 20 4 20 4 11
Label length 20 36 36 25
Parameter Description
title The title of an individual bubble - 80 character max, required
subtitle The subtitle of an individual bubble - 80 character max, optional
imageUrl The URL to the image of the bubble, optional
defaultAction A Default Action Object to trigger when the element is pressed, optional
buttons An array of Button Objects. Button type share can only be used inside carousels. optional, max 3 buttons
richCard A Rich Card Object. Supported by RCS channel type. In case if not specified default values are applied. optional

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.

Rich Card Object Properties

Parameter Description
cardOrientation Orientation of a Rich Card. Supported by standalone Rich Card only. One of VERTICAL, HORIZONTAL. Default value is VERTICAL. optional
cardWidth Width of a Rich Card. Supported by carousel Rich Card only and applied to all carousel card items. One of SMALL, MEDIUM. In case if specified should be set in richCard object for a Message Object. Default value is MEDIUM. optional
imageAlignment Image alignment inside a Rich Card. Supported by standalone Rich Card only with cardOrientation = HORIZONTAL. One of LEFT, RIGHT. Default value is LEFT. optional
mediaHeight Height of a media inside a Rich Card. Supported by carousel or standalone Rich Card with cardOrientation = VERTICAL. The value specified in Carousel Object has priority over one specified in Message Object. One of SHORT, MEDIUM, TALL. Default value for standalone card is TALL, for carousel card is MEDIUM. optional
thumbnailUrl The URL of thumbnail for image or video media content. Can be specified along with media for standalone card in Message Object or carousel card in Carousel Object item. optional
contentDescription The text description of media content used by screen readers. Can be specified along with media for standalone card in Message Object or carousel card in Carousel Object item. optional
forceRefresh A boolean value. When set to true the media file will be downloaded from remote resource again and cached in the system. When set to false or not specified the media file will be taken from the system cache. The value specified in Carousel Object has priority over one specified in Message Object. Default value is false. optional

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,
    "botId":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
botId The Bot 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, "R" = Read.
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,
  "botId":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
botId The Bot 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, "R" = Read.
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
Short Code SMS/MMS dsc
Long Code SMS/MMS dlc
Facebook fb
Twitter twr
Alexa alx
Web Chat web
RCS rcs

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
Short Code SMS/MMS dsc
Long Code SMS/MMS dlc
Facebook fb
Twitter twr
Web Chat web
RCS rcs

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
Short Code SMS/MMS dsc
Long Code SMS/MMS dlc
Facebook fb
Twitter twr
Web Chat web
RCS rcs

Send a Message w/ Buttons

Send a 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
Web Chat web

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
Web Chat web
RCS rcs

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
Web Chat web
RCS rcs

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'
                }
            ]
        }
    ],