Chat messages

put
Send Chat Message

https://api.salemove.com/engagements/{engagement_id}/chat_messages/{message_id}
Sends a chat message to an engagement participant. This endpoint can be used by either the operator or the visitor. The endpoint infers the sender from the authorization headers. - If Authorization header has the operator's bearer token in it, the message is always sent to the visitor. - If Authorization header has the visitor's bearer token in it, the message is always sent to the operator. This endpoint requires a client-generated message ID as a version 4 UUID in the URL. See Webhooks section for receiving chat messages via webhook events.
Request
Response
Request
Path Parameters
engagement_id
required
srting
The ID of the engagement where the message is sent.
message_id
required
srting
Client-generated message ID as a UUID version 4. Submitting the chat message twice with the same ID does not create a duplicate message.
Headers
Authorization
required
string
Bearer access token. NB! Visitor's token to send message to the operator; operator's token to send message to the visitor.
Accept
required
string
Must be application/vnd.salemove.v1+json.
Query Parameters
content
optional
string
The content the sender wishes to send to the recipient. This can only be empty if the message contains a files attachment.
type
optional
string
Chat message type. Type is only used when the target is operator. Default value is chat.
attachment
optional
Attachment
Chat message attachment (see Attachments section for more info).
metadata
optional
object
Chat Message Metadata (see Chat Message Metadata section for more info).
curl --request PUT \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"content": "Message content",
"type": "chat",
"attachment": {
"type": "single_choice",
"image_url": "https://s3.amazonaws.com/hosting-elements.glia.com/Glia-OG.png",
"options": [
{
"text": "Choice 1",
"value": "choice_1"
},
{
"text": "Choice 2",
"value": "choice_2"
},
{
"text": "Choice 3",
"value": "choice_3"
}
]
}
}' \
"https://api.salemove.com/engagements/$engagement_id/chat_messages/$id"
Response
200: OK
{
"timestamp": "2017-09-21T12:43:01Z",
"id": "4cf0d3fe-8f2f-4aad-8e10-c2ffab8929c6",
"engagement_id": "202a50af-8c0e-4e04-9be1-c174a3aabe1a",
"sub_engagement_id": "29f6f027-b3f2-484e-b353-ad993462a4a5",
"content": "Message Content",
"target": "operator",
"type": "chat",
"status": "sent",
"sender": {
"type": "visitor"
},
"attachment": {
"type": "single_choice",
"image_url": "https://s3.amazonaws.com/hosting-elements.glia.com/Glia-OG.png",
"options": [
{
"text": "Choice 1",
"value": "choice_1"
},
{
"text": "Choice 2",
"value": "choice_2"
},
{
"text": "Choice 3",
"value": "choice_3"
}
]
}
}

Chat Message Types

Type

Description

chat

Regular chat message.

event

A message type used to communicate that an action has been performed by the visitor. Events can only be sent by visitors. Also see events.

suggestion

A suggested response to the visitor. Suggestion is visible only to operator and can then be selected and sent to the visitor. Also see AI suggestion.

prompt

A message that is only visible to operator. Prompts are typically used to guide the operator through an engagement. For example, a prompt might suggest offering CoBrowsing to the visitor. Also see AI prompt.

Chat Message Attachment

Attachments let you add more context to a message, enhancing user experience and making it more interactive. Chat message attachment must have type property that defines the behavior of attachment.

Example response to a chat message with an attachment when attachment's option is selected

{
"message": "Choice 2",
"created_at": "2017-09-21T12:44:01.000Z",
"type": "user",
"sender": {
"href": "https://api.salemove.com/visitors/039124e6-b4e8-4a0d-b420-5b6696c7ecb4",
"name": "Sasha Brown",
"type": "visitor"
},
"attachment": {
"type": "single_choice_response",
"selected_option": "choice_2"
}
}

Chat Message Attachment Properties

Parameter

Required

Type

Description

type

Yes

String

Type of the attachment. Can be one of single_choice, single_choice_response, files.

Chat Message Attachment Supported Types

Type

Description

single_choice

Single choice defines a list of options for user to make a simplified decision for the next interaction. Selected option will be sent back to the other party as a regular chat message containing single choice response attachment.

single_choice_response

Response indicates a successful user interaction while passing back also the selection value.

files

A list of files such as image or PDF

Chat Message Attachment Type single_choice_response Parameters

Parameter

Required

Type

Description

selected_option

Yes

String

User interaction based choice selection.

Chat Message Attachment Type single_choice Parameters

Parameter

Required

Type

Description

options

Yes

Array of single choice options

Provides a list of all available choices for the user to choose from.

image_url

No

String

URL of an image displayed on top of the choices expressing clear intent of the cards.

Single Choice Option Structure

Parameter

Required

Type

Description

text

Yes

String

Text displayed to user as a choice label.

value

Yes

String

Value of the choice sent as a response on user interaction.

Chat Message Attachment Type files Parameters

Parameter

Required

Type

Description

files

Yes

String

List of objects containing file ID's that were returned by upload file.

curl --request PUT \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"content": "Message content",
"target": "operator",
"type": "chat",
"attachment": {
"type": "files",
"files": [{"id": "d0b328a4-a5f9-43d8-8ba7-725b0cfffa73"}]
}
}' \
"https://api.salemove.com/engagements/$engagement_id/chat_messages/$id"

Generates the output

{
"timestamp": "2017-09-21T12:43:01Z",
"id": "4cf0d3fe-8f2f-4aad-8e10-c2ffab8929c6",
"engagement_id": "202a50af-8c0e-4e04-9be1-c174a3aabe1a",
"sub_engagement_id": "29f6f027-b3f2-484e-b353-ad993462a4a5",
"content": "Message content",
"target": "operator",
"type": "chat",
"status": "sent",
"sender": {
"type": "visitor"
},
"attachment": {
"type": "files",
"files": [
{
"url": "https://api.salemove.com/engagements/202a50af-8c0e-4e04-9be1-c174a3aabe1a/files/4cf0d3fe-8f2f-4aad-8e10-c2ffab8929c6",
"name": "original_file_name.png",
"content_type": "image/png",
"deleted": false
}
]
}
}

Chat Message Metadata

Chat message metadata allows an integrator to add end to end data inside a JSON object. This information is only relevant to the integrator and will be handled transparently inside Glia.

Metadata can be used, for instance, to customize how a custom response card is rendered.

Custom response cards workflow example:

Chat Message Metadata Properties

Chat message metadata is an optional property of type JSON object specified by the integrator. Any JSON object is allowed.

Chat message metadata examples:

{
"metadata": {
"custom_card_type": "insurance",
"customer_number": "C123456789",
"age": 33
}
}
{
"metadata": {
"custom_card_type": "latest_news",
"custom_card_language": "en-gb",
"customer": "Harry Brown",
"location": "London",
"age": 45
}
}

Chat message metadata property may contain provider object with name property representing the name of message provider.

For example if the message is sent by the operator assistant name property represents operator assistant's name that provided suggestion.

Chat message metadata example with provider name

{
"metadata": {
"provider": {
"name": "Sales Bot"
}
}
}

post
Upload File

https://api.salemove.com/engagements/{engagement_id}/files
Uploads a file that can later be sent as a part of a chat message.The response contains a field security_scanning_required. If the value of this field is true, uploader must wait for the FileSecurityScanResultEvent to arrive before they can send the file as a part of a chat message. Additionally, the scan result must be clean in order to send the file.
Request
Response
Request
Headers
Authorization
required
string
Used to authenticate the user. Only Bearer access token is allowed.
Accept
required
string
Must be application/vnd.salemove.v1+json
Content-Type
required
string
The endpoint accepts multipart/form-data and application/x-www-form-urlencoded content types.
Query Parameters
content
required
File
File to be uploaded. Maximum file size is 25 MB by default and 5 MB for SMS/WhatsApp visitors. Only files with MIME types set in site settings can be uploaded. For more, see allowed_file_content_types setting.
curl --request POST \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--form "content=@picture.png" \
"https://api.salemove.com/engagements/$engagement_id/files"
Response
200: OK
{
"file_id": "d0b328a4-a5f9-43d8-8ba7-725b0cfffa73",
"security_scanning_required": true
}

get
Download File

https://api.salemove.com/engagements/{engagement_id}/files/{file_id}
Downloads a file that is part of an engagement (for example, the file has been sent as part of a chat message). Returns either the contents of the file or a download URL depending on the Accept header (see below).
Request
Response
Request
Headers
Authorization
required
string
Used to authenticate the user. Only Bearer access token is allowed.
Accept
optional
string
Must be one of application/vnd.salemove.v1+json or */* (defaults to */* if not specified).If the value is application/vnd.salemove.v1+json, returns a JSON response containing file_url, which is a temporary file download URL that expires after a short while. If the value is */*, returns the contents of the requested file.
curl --request GET \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
"https://api.salemove.com/engagements/$engagement_id/files/$file_id"
Response
200: OK
{
"file_url": "https://example.com/file"
}