Engagement Requests

Authentication

Engagement requests can be created by

  • Operators using the Glia platform

  • Visitors with a Glia session (e.g present on a Glia enabled Site using a web

    browser)

  • Visitors from external systems - Glia integrators

Operators Using the Glia Platform

Operators using the Glia system are provided an API token upon the user's creation. When creating an engagement request, the Authorization header must contain the user's bearer access token.

curl --request POST \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"visitor_id": "c62b4a91-a0d7-4137-80e3-c281393b71c2",
"site_id": "51138845-3c46-4c21-8bd8-1cf45957f62e",
"media": "text"
}' \
"https://api.salemove.com/engagement_requests"

Visitors with a Glia Session

Visitors connected to a Glia enabled site using a web browser are provided session IDs to uniquely identify the visitor and the site. Currently there is no way to register visitor sessions as a integrator using the REST API, instead use the Visitors from external system method. When creating an engagement request, the Authorization header must contain the visitor's Session ID and the X-Salemove-Visit-Session-Id headers must contain the visitor's Visit Session ID. These headers are set automatically when creating engagement requests using the Glia JavaScript API.

curl --request POST \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json' \
--data-binary '{
"operator_id": "c62b4a91-a0d7-4137-80e3-c281393b71c2",
"media": "text",
"source": "sdk"
}' \
"https://api.salemove.com/engagement_requests"

Visitors from External systems - Glia Integrators

Integrators of the Glia system might want to engage operators with visitors outside of the context of a web browser or without using the Glia JavaScript API.

In this case the integrator can create a visitor using Create Site Visitor endpoint. By specifying visitor_integrator as a source parameter and using an access token provided in the response the integrator can create an engagement request on behalf the visitor.

curl --request POST \
--header "Authorization: Bearer $visitor_access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"operator_id": "c62b4a91-a0d7-4137-80e3-c281393b71c2",
"media": "text",
"site_id": "51138845-3c46-4c21-8bd8-1cf45957f62e",
"source": "visitor_integrator"
}' \
"https://api.salemove.com/engagement_requests"

POST /engagement_requests

cURL
JavaScript
Ruby
cURL
curl --request POST \
--header "Authorization: Bearer $visitor_access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"operator_id": "c62b4a91-a0d7-4137-80e3-c281393b71c2",
"media": "text",
"site_id": "51138845-3c46-4c21-8bd8-1cf45957f62e",
"source": "visitor_integrator",
"webhooks": [
{
"url": "https://server.com/salemove/events/engagement_start",
"method": "POST",
"headers": {"header_name": "header_value"},
"events": ["engagement.start"]
},
{
"url": "https://server.com/salemove/events/chat_message",
"method": "PUT",
"events": ["engagement.chat.message"]
}
]
}' \
"https://api.salemove.com/engagement_requests"
JavaScript
var XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api.salemove.com/engagement_requests', false);
xhr.setRequestHeader('authorization', `Bearer ${visitorAccessToken}`);
xhr.setRequestHeader('accept', 'application/vnd.salemove.v1+json');
xhr.setRequestHeader('content-type', 'application/json');
var data = {
operator_id: 'c62b4a91-a0d7-4137-80e3-c281393b71c2',
site_id: '51138845-3c46-4c21-8bd8-1cf45957f62e',
source: 'visitor_integrator',
media: 'text',
webhooks: [
{
url: 'https://server.com/salemove/events/engagement_start',
method: 'POST',
headers: {header_name: 'header_value'},
events: ['engagement.start']
},
{
url: 'https://server.com/salemove/events/chat_message',
method: 'PUT',
events: ['engagement.chat.message']
}
]
};
var query = JSON.stringify(data);
xhr.send(query);
var response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
ENDPOINT = 'https://api.salemove.com/engagement_requests'
visitor_access_token = ARGV[0].strip
headers = {
:authorization => "Bearer #{visitor_access_token}",
:accept => "application/vnd.salemove.v1+json",
'Content-Type' => 'application/json'
}
options = {
headers: headers,
query: {
"operator_id": "c62b4a91-a0d7-4137-80e3-c281393b71c2",
"site_id": "51138845-3c46-4c21-8bd8-1cf45957f62e",
"source": "visitor_integrator",
"media": "text",
"webhooks": [
{
"url": "https://server.com/salemove/events/engagement_start",
"method": "POST",
"headers": {"header_name": "header_value"},
"events": ["engagement.start"]
},
{
"url": "https://server.com/salemove/events/chat_message",
"method": "PUT",
"events": ["engagement.chat.message"]
}
]
}
}
raw_response = HTTParty.post(
ENDPOINT,
options
)
response = JSON.parse raw_response.body
puts response

Generates the output

{
"id": "59b0d786-e59a-4c62-a064-05e4f47488a2",
"timeout": 30,
"site_id": "51138845-3c46-4c21-8bd8-1cf45957f62e",
"platform": "omnicore"
}

Action: POST /engagement_requests

Creates an engagement request and notifies the target operator or visitor. The endpoint requires different parameters based on the requester. The timeout field in the response notes in how many seconds (counting from the moment that Glia servers received the request) the engagement request will automatically time out unless the engagement request is accepted, acknowledged, canceled or declined.

The endpoint accepts the following parameters:

Parameter

Required

Type

Description

visitor_id

Yes if request made by operator, ignored otherwise

String

The ID of the visitor who the request will be sent to.

operator_id

Yes if request made by visitor or visitor integrator, ignored otherwise

String

The operator ID who the request will be sent to.

site_id

Yes

String

The site ID of the visitor who the request will be sent to.

media

Yes

String

The initial engagement media type. One of text, phone, audio, video. Can only be text or phone if the request is made by a visitor integrator.

media_options

No

Object

Any additional parameters for the desired media type. Further described below.

source

Yes if request made by visitor or visitor integrator, ignored otherwise

String

Engagement starting source, see Engagement sources.

webhooks

No

Array of webhooks

A list of webhooks that will subscribe to engagement request or engagement events. Only events regarding this engagement request and the engagement that is created by accepting this engagement request will be sent. Webhooks can have overlapping sets of events. A maximum of 10 webhooks are allowed.

media_options

Field

Required

Type

Description

phone_number

Yes if media is phone

String

The phone number (including the country prefix) that will be called.

phone_extension

No

String

Phone number extension that is used when calling phone_number. A valid extension contains 1-7 digits and any number of , characters. There is an initial two second delay time before the first extension character is processed. Each , character in the extension adds a two second wait time before the next character is processed. Maximum length is 25 characters.

one_way

No

Boolean

Optional. When set to true, the video will start from the operator to the visitor only. When set to false, the video starts both ways - from the operator to the visitor and from the visitor to the operator. The default value is true.

Accept Engagement Request

cURL
JavaScript
Ruby
cURL
curl --request PATCH \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"action": "accept",
"media": "text",
"webhooks": [
{
"url": "https://server.com/salemove/events/chat_message",
"method": "PUT",
"events": ["engagement.chat.message"]
}
]
}' \
"https://api.salemove.com/engagement_requests/$engagement_request_id"
JavaScript
var XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
var xhr = new XMLHttpRequest();
xhr.open(
'PATCH',
`https://api.salemove.com/engagement_requests/${engagement_request_id}`,
false
);
xhr.setRequestHeader('authorization', `Bearer ${accessToken}`);
xhr.setRequestHeader('accept', 'application/vnd.salemove.v1+json');
xhr.setRequestHeader('content-type', 'application/json');
var data = {
action: 'accept',
media: 'text'
};
var query = JSON.stringify(data);
xhr.send(query);
var response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
ENDPOINT = 'https://api.salemove.com/engagement_requests'
access_token = ARGV[0].strip
engagement_request_id = ARGV[1].strip
headers = {
:authorization => "Bearer #{access_token}",
:accept => "application/vnd.salemove.v1+json",
"Content-Type" => 'application/json'
}
options = {
headers: headers,
query: {
"action": "accept",
"media": "text"
}
}
raw_response = HTTParty.patch(
"#{ENDPOINT}/#{engagement_request_id}",
options
)
response = JSON.parse raw_response.body
puts response

Generates the output

{
"id": "59b0d786-e59a-4c62-a064-05e4f47488a2",
"engagement_id": "37035d9f-2dfc-47f1-9290-0555b5106997",
"sub_engagement_id": "51138845-3c46-4c21-8bd8-1cf45957f62e"
}

Action: PATCH /engagement_requests with action: "accept"

Accepts the engagement request and starts an engagement. The endpoint requires the media parameter. Only the recipient of the engagement request can accept it, i.e if an engagement request was sent by operator O to visitor V, then only visitor V is authorized to accept the engagement request.

The endpoint accepts the following parameters:

Parameter

Required

Type

Description

media

Yes

String

The initial engagement media type. Must be one of text, phone, audio, video. Can only be text if the request is made by a visitor integrator.

media_options

No

Object

Any additional parameters for the desired media type. Further described below.

webhooks

No

Array of webhooks

A list of webhooks that will subscribe to engagement events in addition to the list of webhooks specified when this engagement request was created. Only events regarding the engagement that is created by accepting this engagement request will be sent. Webhooks can have overlapping sets of events. A maximum of 10 webhooks are allowed.

media_options

Field

Required

Type

Description

phone_number

Yes if media is phone

String

The phone number (including the country prefix) that will be called.

phone_extension

No

String

Phone number extension that is used when calling phone_number. A valid extension contains 1-7 digits and any number of , characters. There is an initial two second delay time before the first extension character is processed. Each , character in the extension adds a two second wait time before the next character is processed. Maximum length is 25 characters.

one_way

No

Boolean

Optional. When set to true, the video will start from the operator to the visitor only. When set to false, the video starts both ways - from the operator to the visitor and from the visitor to the operator. The default value is true.

To end the engagement, see End Engagement.

Decline Engagement Request

cURL
JavaScript
Ruby
cURL
curl --request PATCH \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"action": "decline"
}' \
"https://api.salemove.com/engagement_requests/$engagement_request_id"
JavaScript
var XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
var xhr = new XMLHttpRequest();
xhr.open(
'PATCH',
'https://api.salemove.com/engagement_requests/' + $engagement_request_id,
false
);
xhr.setRequestHeader('authorization', `Bearer ${accessToken}`);
xhr.setRequestHeader('accept', 'application/vnd.salemove.v1+json');
xhr.setRequestHeader('content-type', 'application/json');
var data = {
action: 'decline'
};
var query = JSON.stringify(data);
xhr.send(query);
var response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
ENDPOINT = 'https://api.salemove.com/engagement_requests'
access_token = ARGV[0].strip
engagement_request_id = ARGV[1].strip
headers = {
:authorization => "Bearer #{access_token}",
:accept => "application/vnd.salemove.v1+json",
"Content-Type" => 'application/json'
}
options = {
headers: headers,
query: {
"action": "decline"
}
}
raw_response = HTTParty.patch(
"#{ENDPOINT}/#{engagement_request_id}",
options
)
response = JSON.parse raw_response.body
puts response

Generates the output

{
"id": "59b0d786-e59a-4c62-a064-05e4f47488a2"
}

Action: PATCH /engagement_requests with action: "decline"

Declines the engagement request (i.e if the recipient of the engagement request is unable to engage at this time). Only the recipient of the engagement request can decline it, i.e if an engagement request was sent by operator O to visitor V, then only visitor V is authorized to decline the engagement request.

Cancel Engagement Request

cURL
JavaScript
Ruby
cURL
curl --request PATCH \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"action": "cancel"
}' \
"https://api.salemove.com/engagement_requests/$engagement_request_id"
JavaScript
var XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
var xhr = new XMLHttpRequest();
xhr.open(
'PATCH',
`https://api.salemove.com/engagement_requests/${engagement_request_id}`,
false
);
xhr.setRequestHeader('authorization', `Bearer ${accessToken}`);
xhr.setRequestHeader('accept', 'application/vnd.salemove.v1+json');
xhr.setRequestHeader('content-type', 'application/json');
var data = {
action: 'cancel'
};
var query = JSON.stringify(data);
xhr.send(query);
var response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
ENDPOINT = 'https://api.salemove.com/engagement_requests'
access_token = ARGV[0].strip
engagement_request_id = ARGV[1].strip
headers = {
:authorization => "Bearer #{access_token}",
:accept => "application/vnd.salemove.v1+json",
"Content-Type" => 'application/json'
}
options = {
headers: headers,
query: {
"action": "cancel"
}
}
raw_response = HTTParty.patch(
"#{ENDPOINT}/#{engagement_request_id}",
options
)
response = JSON.parse raw_response.body
puts response

Generates the output

{
"id": "59b0d786-e59a-4c62-a064-05e4f47488a2"
}

Action: PATCH /engagement_requests with action: "cancel"

Cancels the engagement request.

Only the originator of the engagement request can cancel it, i.e if an engagement request was sent by visitor V to operator O, then only visitor V is allowed to cancel the engagement request. Note that if an engagement is already started, canceling the engagement request will end the engagement instead. This functionality is provided due to possible data races between accepting and canceling an engagement request.