Alvaria Cloud Server Messaging REST API v2.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Overview

The Alvaria™ Cloud Server Messaging REST APIs enable a custom server application to register and send messages and events using a text-based interaction. This interaction can also contain URLs for multimedia files. The registered session has a maximum life cycle of 4 hours and will be disconnected by Alvaria™ Cloud if the session is still active after 4 hours.

Custom server applications will receive messages and events through the preconfigured callback/webhook URL. These events and messages are defined in Calback Event List.

Backoff and retry procedures should be implemented for when error conditions occur (e.g. network outages, throttling, etc)

Steps to Invoke Server Messaging APIs

Get oauth Token

The first step is to get an Alvaria™ oauth access token. The Alvaria™ REST API endpoint oauth token generation process is defined in Alvaria™ Cloud REST API Developer's Guide.

The return value's access_token is used as the Bearer token in all subsequent REST calls.

  // Alvaria™ oauth token example response
  {
    "access_token": "fc1fee03-c4a2-4db4-add7-dd6c0542ff93",
    "scope": "servermessagingapi",
    "token_type": "Bearer",
    "expires_in": 3599
  }

Establish a Server Messaging Session

To create a server messaging session with Alvaria™ Cloud call the Create Session endpoint, which responds with a provisional Server Messaging sessionId. Upon successful creation of the Server Messaging session, a New Session event will be sent as a callback event with status SUCCESS. The return value's 'sessionId' is used as the 'server-messaging-session-id' header in all subsequent Server Messaging REST API calls.

Send Message

To send messages to the Alvaria™ Cloud call the Send Message endpoint. The Server Messaging 'sessionId' from the previous step needs to be passed in each request. For every message sent, a unique 'messageId' will be returned. In case of any failure in processing the message sent, Message Status event will be sent with status FAILED.

Disconnect a Server Messaging Session

The client can end a Server Messaging session by calling the Delete Session endpoint, which will immediately send a wrap message to the Agent (if there is one in the session). A Session End event will be sent as a callback event with the result of the request.

Callback Event List

Callback (webhook) events received from Server Messaging API are grouped by category:

• System Events
• Messages

Authentication of all server messaging callback events and messages can be performed using Alvaria Cloud generated JWT tokens.

System Events

The table below describes the events that may be generated when Server Messaging API calls are made or when the system initiates notifications such as interaction state changes.

Event Type		Description
NEW_SESSION		This event is received in response to a POST session request. This event informs the client that the Server Messaging session has been created successfully or not.
AGENT_JOINED		This event indicates that an agent has joined to a Server Messaging session.
MESSAGE_STATUS		This event indicates the status of a POST message request.
SESSION_REROUTE		This event informs the client that the call has been transferred to a worktype or agent.
SESSION_END		This event will signal that client session has been disconnected from the Alvaria™ Cloud. Once you receive this event you should not use the server messaging sessionId anymore.

Messages

The table below describes the message that may be generated by the system or passed from an agent.

Type		Description
MESSAGE		This event indicates that text or attachment has been received from the system or agent.

Configure Webhook URL

Before you can start receiving Server Messaging notifications you will need to create an endpoint (Callback URL) on your server to receive notifications. Once the callback URL is configured please share it with Alvaria Customer Care so that a manual configuration step can be completed.

Callback URL Specifications:

• Callback URL must be reachable from the Alvaria System
• Callback URL must be able to process HTTPS requests
• Callback URL is like any regular URL. For example: https://www.example.com/webhooks/server-messaging
• When Alvaria Server Messaging sends a webhook request to your callback URL then:
  • Your server response with an HTTP status code 200 is considered as successful.
  • If your server responds with an HTTP status code other than 200, or if we are unable to deliver the webhook for another reason, we will keep trying with decreasing frequency until the request succeeds, for up to 4 hours.

Callback Event Authentication

Each Server Messaging callback request includes a JSON Web Token (JWT) in the ‘Authorization’ header. This token is signed using a preconfigured private key based on the RS256 algorithm. A corresponding public key is also generated, which can be used to verify the integrity and authenticity of the JWT. The key pair is generated once the callback URL is provided to Alvaria Customer Care as described in the Configure Webhook URL section. You will receive the public key securely after configuration is complete.

Base URLs:

• https://orgId.via.aspect-cloud.net

License: License: Creative Commons Attribution 4.0 International Public License

Authentication

• oAuth2 authentication.

  • Flow: client crendentials
  • Authorization URL = https://myaspect.{region}.id.aspect-cloud.net/tokenservice/oauth2/access_token

Scope	Scope Description
servermessagingapi	manage access to server messaging api

Session

Create Session

Code samples

# You can also use wget
curl -X POST https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/session \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: string' \
  -H 'x-api-key: string'

const fetch = require('node-fetch');
const inputBody = {
  "workTypeId": 32,
  "contactName": "Customer Name",
  "integration": "SMS"
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'string',
  'x-api-key':'string'
};

fetch('https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/session',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/session HTTP/1.1
Host: orgid.via.aspect-cloud.net
Content-Type: application/json
Accept: application/json
Authorization: string
x-api-key: string

POST /via/v2/organizations/{orgId}/serverMessaging/session

Creates a new Server Messaging Session.

Body parameter

{
  "workTypeId": 32,
  "contactName": "Customer Name",
  "integration": "SMS"
}

Parameters

Name	In	Type	Required	Description
orgId	path	string	true	Name of a customer organization
Authorization	header	string	true	Authentication token with the value: 'Bearer {accessToken}', where {accessToken} was returned from a call to the authorization endpoint.
x-api-key	header	string	true	Alvaria-provided value used to track API endpoint usage
body	body	NewSession	true	Name/Value pairs that are stored within the Session that can be accessed for channel specific functionality

Example responses

202 Response

{
  "sessionId": "ab7dbcbc-c041-4ac0-8ca0-5a0961f7be5"
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Accepted	SessionResponse
400	Bad Request	Bad Request	ErrorResponse
401	Unauthorized	Unauthorized	None
404	Not Found	Not Found	ErrorResponse
405	Method Not Allowed	Method Not Allowed	ErrorResponse
429	Too Many Requests	Too Many Requests	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Delete Session

Code samples

# You can also use wget
curl -X DELETE https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/session \
  -H 'Accept: application/json' \
  -H 'Authorization: string' \
  -H 'server-messaging-session-id: string' \
  -H 'x-api-key: string'

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'string',
  'server-messaging-session-id':'string',
  'x-api-key':'string'
};

fetch('https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/session',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/session HTTP/1.1
Host: orgid.via.aspect-cloud.net
Accept: application/json
Authorization: string
server-messaging-session-id: string
x-api-key: string

DELETE /via/v2/organizations/{orgId}/serverMessaging/session

Deletes an existing Server Messaging Session.

Parameters

Name	In	Type	Required	Description
orgId	path	string	true	Name of a customer organization
Authorization	header	string	true	Authentication token with the value: 'Bearer {accessToken}', where {accessToken} was returned from a call to the authorization endpoint.
server-messaging-session-id	header	string	true	Identifier representing the specific Server Messaging session. This is the 'sessionId' retruned from Create Session request.
x-api-key	header	string	true	Alvaria-provided value used to track API endpoint usage

Example responses

400 Response

{
  "code": 404,
  "message": "not found",
  "errors": [
    {
      "scope": "scope",
      "reason": "reason",
      "message": "message"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Accepted	None
400	Bad Request	Bad Request	ErrorResponse
401	Unauthorized	Unauthorized	None
404	Not Found	Not Found	ErrorResponse
405	Method Not Allowed	Method Not Allowed	ErrorResponse
429	Too Many Requests	Too Many Requests	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Message

Send Message

Code samples

# You can also use wget
curl -X POST https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/message \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: string' \
  -H 'x-api-key: string' \
  -H 'server-messaging-session-id: string'

const fetch = require('node-fetch');
const inputBody = {
  "text": "Hello there.",
  "attachment": {
    "type": "Image",
    "url": "http://www.mydomain.com/image/graphics01.jpg"
  }
};
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'string',
  'x-api-key':'string',
  'server-messaging-session-id':'string'
};

fetch('https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/message',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST https://orgId.via.aspect-cloud.net/via/v2/organizations/{orgId}/serverMessaging/message HTTP/1.1
Host: orgid.via.aspect-cloud.net
Content-Type: application/json
Accept: application/json
Authorization: string
x-api-key: string
server-messaging-session-id: string

POST /via/v2/organizations/{orgId}/serverMessaging/message

This sends a request to the Server Messaging subsystem containing text and or url.

Body parameter

{
  "text": "Hello there.",
  "attachment": {
    "type": "Image",
    "url": "http://www.mydomain.com/image/graphics01.jpg"
  }
}

Parameters

Name	In	Type	Required	Description
orgId	path	string	true	Name of customer organization.
Authorization	header	string	true	Authentication token with the value: 'Bearer {accessToken}', where {accessToken} was returned from a call to the authorization endpoint.
x-api-key	header	string	true	Alvaria-provided value used to track API endpoint usage
server-messaging-session-id	header	string	true	Identifier representing the specific Server Messaging session. This is the 'sessionId' retruned from Create Session request.
body	body	Message	true	none

Example responses

202 Response

{
  "messageId": "22D45513-66F7-4A02-9998-EF8E72AB2363"
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Accepted	MessageResponse
400	Bad Request	Bad Request	ErrorResponse
401	Unauthorized	Unauthorized	None
404	Not Found	Not Found	ErrorResponse
405	Method Not Allowed	Method Not Allowed	ErrorResponse
429	Too Many Requests	Too Many Requests	ErrorResponse
500	Internal Server Error	Internal Server Error	ErrorResponse

Response Headers

Status	Header	Type	Format	Description
202	Access-Control-Allow-Origin	string		none

Schemas

NewSession

{
  "workTypeId": 32,
  "contactName": "Customer Name",
  "integration": "SMS"
}

Properties

Name	Type	Required	Restrictions	Description
workTypeId	string	true	none	Alvaria-generated unique identifier for the WorkType.
contactName	string	true	none	Name of the contact the interaction originated from. Typically the customer name.
integration	string	false	none	Integration type the custom server application is using for tracking purposes

SessionResponse

{
  "sessionId": "ab7dbcbc-c041-4ac0-8ca0-5a0961f7be5"
}

Properties

Name	Type	Required	Restrictions	Description
sessionId	string	true	none	Alvaria-generated unique identifier for the Server Messaging Session. Use this identifier in all subsequent Server Messaging API calls for this session.

Message

{
  "text": "Hello there.",
  "attachment": {
    "type": "Image",
    "url": "http://www.mydomain.com/image/graphics01.jpg"
  }
}

Properties

Name	Type	Required	Restrictions	Description
text	string	false	none	none
attachment	Attachment	false	none	none

Attachment

{
  "type": "Image",
  "url": "http://www.mydomain.com/image/graphics01.jpg"
}

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Attachment type
url	string	true	none	URL to the attachment

Enumerated Values

Property	Value
type	Image
type	File
type	Audio
type	Video

MessageResponse

{
  "messageId": "22D45513-66F7-4A02-9998-EF8E72AB2363"
}

Properties

Name	Type	Required	Restrictions	Description
messageId	string	true	none	Alvaria-generated unique identifier for the message

ErrorResponse

{
  "code": 404,
  "message": "not found",
  "errors": [
    {
      "scope": "scope",
      "reason": "reason",
      "message": "message"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
code	integer	false	none	HTTP error status
message	string	false	none	none
errors	[Error]	false	none	none

Error

{
  "scope": "scope",
  "reason": "reason",
  "message": "message"
}

Properties

Name	Type	Required	Restrictions	Description
scope	string	false	none	none
reason	string	false	none	none
message	string	false	none	none

NewSessionCallback

{
  "sessionId": "38D1FBA0-2079-42FB-93C2-0DE301CF8FF5",
  "event": "NEW_SESSION",
  "status": "SUCCESS",
  "eventId": "22D45513-66F7-4A02-9998-EF8E72AB2363"
}

A client will receive this event in response to a Create Session request.

Properties

Name	Type	Required	Restrictions	Description
sessionId	string	true	none	Alvaria-generated unique identifier for a server messaging session
event	string	true	none	Type of event.
status	string	true	none	Status of the event.
statusMessage	string	false	none	Status message if available. Present only when status is FAILED
eventId	string	true	none	Alvaria-generated unique identifier for the event

Enumerated Values

Property	Value
event	NEW_SESSION
status	SUCCESS
status	FAILED

AgentJoinedCallback

{
  "sessionId": "38D1FBA0-2079-42FB-93C2-0DE301CF8FF5",
  "event": "AGENT_JOINED",
  "agentAlias": "John",
  "eventId": "22D45513-66F7-4A02-9998-EF8E72AB2363"
}

An agent has been added to the server messaging session.

Properties

Name	Type	Required	Restrictions	Description
sessionId	string	true	none	Alvaria-generated unique identifier for a server messaging session
event	string	true	none	Type of event.
agentAlias	string	true	none	Agent's first name
eventId	string	true	none	Alvaria-generated unique identifier for the event

Enumerated Values

Property	Value
event	AGENT_JOINED

MessageStatusCallback

{
  "sessionId": "38D1FBA0-2079-42FB-93C2-0DE301CF8FF5",
  "event": "MESSAGE_STATUS",
  "status": "FAILED",
  "messageId": "d1e73bad-6efe-462f-8182-913f2f1306b4",
  "statusMessage": "Session does not exist",
  "eventId": "22D45513-66F7-4A02-9998-EF8E72AB2363"
}

A client will receive this event in response to a Send Message request. This will only be sent for failed messages.

Properties

Name	Type	Required	Restrictions	Description
sessionId	string	true	none	Alvaria-generated unique identifier for a server messaging session
event	string	true	none	Type of event.
status	string	true	none	Status of the message
messageId	string	true	none	MessageId returned during POST message request
statusMessage	string	false	none	Status message if availble. Present only when status is FAILED
eventId	string	true	none	Alvaria-generated unique identifier for the event

Enumerated Values

Property	Value
event	MESSAGE_STATUS
status	FAILED

SessionReRouteCallback

{
  "sessionId": "38D1FBA0-2079-42FB-93C2-0DE301CF8FF5",
  "event": "SESSION_REROUTE",
  "eventId": "22D45513-66F7-4A02-9998-EF8E72AB2363",
  "agentAlias": "John"
}

Server messaging session has been rerouted to a worktype or agent

Properties

Name	Type	Required	Restrictions	Description
sessionId	string	true	none	Alvaria-generated unique identifier for a server messaging session.
event	string	true	none	Type of event.
agentAlias	string	false	none	Agent's first name to which the interaction rerouted. Present only if interaction is rerouted to an agent.
worktypeId	string	false	none	Worktype Id to which the interaction rerouted. Present only if interaction is rerouted to a worktype.
eventId	string	true	none	Alvaria-generated unique identifier for the event

Enumerated Values

Property	Value
event	SESSION_REROUTE

SessionEndCallback

{
  "sessionId": "38D1FBA0-2079-42FB-93C2-0DE301CF8FF5",
  "event": "SESSION_END",
  "status": "SUCCESS",
  "from": "SYSTEM",
  "eventId": "22D45513-66F7-4A02-9998-EF8E72AB2363"
}

A client will receive this event in response to a Delete Session request or signal that the Server Messaging session has been disconnected by Alvaria™ Cloud.

Properties

Name	Type	Required	Restrictions	Description
sessionId	string	true	none	Alvaria-generated unique identifier for a server messaging session
event	string	true	none	Type of event.
status	string	true	none	Status of the event.
from	string	false	none	Only present if Session is disconnected by Alvaria™ Cloud.
eventId	string	true	none	Alvaria-generated unique identifier for the event

Enumerated Values

Property	Value
event	SESSION_END
status	SUCCESS
status	FAILED
from	SYSTEM

MessageCallback

{
  "sessionId": "38D1FBA0-2079-42FB-93C2-0DE301CF8FF5",
  "senderId": "SYSTEM",
  "message": {
    "text": "Hello there.",
    "attachment": {
      "type": "Image",
      "url": "http://www.mydomain.com/image/graphics01.jpg"
    }
  },
  "eventId": "22D45513-66F7-4A02-9998-EF8E72AB2363"
}

This event signals that a message has been sent from Alvaria™.

Properties

Name	Type	Required	Restrictions	Description
sessionId	string	true	none	Alvaria-generated unique identifier for a server messaging session
senderId	string	true	none	Origin of message (agent/system).
message	Message	true	none	none
eventId	string	true	none	Alvaria-generated unique identifier for the event