Messages

You can use the API to get the message information.

The Message model

Field	Type	Description
id	String	The unique identifier for the message which is given by Pingstreams.
sender	String	A unique identifier of the sender. It can be: the user identifier, a bot identifier or the system user
senderFullname	String	The sender fullname. It can be: the user fullname, the bot name or an alias
recipient	String	A unique identifier of the recipient. It can be: the request_id field (external id) of the request
status	Number	The message status: FAILED : -100, SENDING : 0, SENT : 100, DELIVERED : 150, RECEIVED : 200, RETURN_RECEIPT: 250, SEEN : 300
text	String	The message text.
type	String	The message type. Accepted values: text (default), image
metadata	Object	The message metadata.
attributes	Object	The custom attributes which are set for the message.
createdAt	String	The time (ISO-8601 date string) when the message was created.
updatedAt	String	The time (ISO-8601 date string) when the message was updated.
createdBy	String	The unique identifier of the row creator
id_project	String	The unique identifier of the project

Send a message

POST https://api.pingstreams.com/v3/:project_id/requests/:request_id/messages

Allows to send a message. This method also creates a new conversation (request) if it didn’t exist at the time of the call.

Path Parameters

Parameter	Type	Description
project_id	string	The project_id is a unique code assigned to your project when you create it in Pingstreams
request_id	string	The request identifier. Must follow this pattern ‘support-group-UUID’

Headers

Header	Type	Description
Authorization	string	authorization token. Basic Auth or JWT
Content-Type	string	use “application/json” value

Request Body

Field	Type	Description
text	string	the message text
departmentid	string	The selected department identifier. Accepted only on the first message.
sourcePage	string	The source page of the request. Accepted only on the first message.
language	string	The language of the request. Accepted only on the first message.
userAgent	string	The userAgent string of the request. Accepted only on the first message.
attributes	object	it’s the message custom attributes. Example: attributes = {"custom_attribute1": "value1"}. You can also use attributes to enable advanced features.
type	string	it’s the message type. “text” value for textual message and “image” for sending image message(you must set metadata field). Available values: text (default) and image.
metadata	object	it’s the image properties: src is the absolute source path of the image, width is the image width, height is the image height. Width and height are optional. Example: metadata = { "src": "https://www.pingstreams.com/wp-content/uploads/2018/03/pingstreams-logo.png", "width": 200, "height": 200 }

Response

{
"_id":"5c81593adf767b0017d1aa68",
"updatedAt":"2019-03-07T17:47:38.411Z",
"createdAt":"2019-03-07T17:47:38.411Z",
"sender":"SRbb2PfbSFcgICv9VQBcURZeloh1",
"senderFullname":"Guest",
"recipient":"support-group-L_OG76RYhR0XFiMf2PK",
"text":"hello from api",
"id_project":"5b55e806c93dde00143163dd",
"createdBy":"SRbb2PfbSFcgICv9VQBcURZeloh1",
"__v":0,
"status":200
}

Example sending text message:

curl -v -X POST -H 'Content-Type: application/json' -u user@example.com:123456 -d '{"text":"hello from api"}' https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/requests/support-group-1234/messages

Example sending image:

curl -v -X POST -H 'Content-Type: application/json' -u user@example.com:123456 -d '{"text":"Alternative text from api", "type":"image", "metadata": {"src": "https://pingstreams.com/pingstreams-logo-x1.png", "width": 200, "height": 200}}' https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/requests/support-group-1234/messages

Attributes

When you send a message you can use the following attributes to activate advanced features:

• attributes.clienttimestamp: use this property to force the message timestamp in milliseconds. This parameter is used by the clients (widgets and chat agents) to perform a client side reordering of messages based on the value of the timestamp field. This property doesn’t guarantees the order of arrival, but only the ordering or reordering on the client side.
• attributes.attachment: use this property to set the response additional reply componenst as quick replies, buttons, links etc. (see: https://developer.pingstreams.com/widget/advanced/widget-json-protocol)
• attributes.subtype.info: If “true” it hides the message to the end-user channels (Widget, whatsapp, Telegram, Facebook etc.)
• attributes.microlanguage: set this property to true to enable the microlanguage pre-processor. You can find more info here: Chatbot buttons, images, video and microlanguage example
• attributes.disableInputMessage: if true it disables the input message, until the next message arrival
• attributes.inputMessagePlaceholder: if set, it modify the default input text placeholder
• attributes.updateUserEmail and attributes.updateUserFullname: If set, the back forward user fullname and email to the widget. Useful if you set user fullname or email in a webhook or external service.

Advanced features

Pingstreams uses Chat21 as messaging engine. When you send a message to Pingstreams using the REST API, Pingstreams will forward the call to the Chat21 REST API. You can see how the Chat21 REST Api works here: https://github.com/chat21/chat21-cloud-functions/blob/master/docs/api.md#send-a-message

You can enable special message features following this paragraph: https://github.com/chat21/chat21-cloud-functions/blob/master/docs/api.md#message-attributes

Get the messages of a request by id

GET https://api.pingstreams.com/v3/:project_id/requests/:request_id/messages

Fetches the messages by his or her request_id

Path Parameters

Parameter	Type	Description
request_id	string	the request_id field. It’s the external request identifier.
project_id	string	the Project Id is a unique code assigned to your project when you create it in Pingstreams.

Headers

Header	Type	Description
Authorization	string	authorization token. Basic Auth or JWT

Response

[
{
"_id":"5c81593adf767b0017d1aa68",
"updatedAt":"2019-03-07T17:47:38.411Z",
"createdAt":"2019-03-07T17:47:38.411Z",
"sender":"SRbb2PfbSFcgICv9VQBcURZeloh1",
"senderFullname":"Guest",
"recipient":"support-group-L_OG76RYhR0XFiMf2PK",
"text":"test56",
"id_project":"5b55e806c93dde00143163dd",
"createdBy":"SRbb2PfbSFcgICv9VQBcURZeloh1",
"__v":0,
"status":200
},
{
"_id":"5c81593adf767b0017d1aa69",
"updatedAt":"2019-03-07T17:47:38.625Z",
"createdAt":"2019-03-07T17:47:38.625Z",
"sender":"system",
"senderFullname":"Bot",
"recipient":"support-group-L_OG76RYhR0XFiMf2PK",
"text":"La stiamo mettendo in contatto con un operatore. Attenda...",
"id_project":"5b55e806c93dde00143163dd",
"createdBy":"system",
"__v":0,
"status":200
}
]

Example:

curl -v -X GET -u user@example.com:123456 https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/requests/support-group-L_OG76RYhR0XFiMf2PK/messages

Get the message by request id and message id

GET https://api.pingstreams.com/v3/:project_id/requests/:request_id/messages/:message_id

Fetche the message by his or her id

Path Parameters

Parameter	Type	Description
request_id	string	the request_id field. It’s the external request identifier.
message_id	string	the message identifier
project_id	string	the Project Id is a unique code assigned to your project when you create it in Pingstreams.

Headers

Header	Type	Description
Authorization	string	authorization token. Basic Auth or JWT

Response

{
"_id":"5c81593adf767b0017d1aa68",
"updatedAt":"2019-03-07T17:47:38.411Z",
"createdAt":"2019-03-07T17:47:38.411Z",
"sender":"SRbb2PfbSFcgICv9VQBcURZeloh1",
"senderFullname":"Guest",
"recipient":"support-group-L_OG76RYhR0XFiMf2PK",
"text":"test56",
"id_project":"5b55e806c93dde00143163dd",
"createdBy":"SRbb2PfbSFcgICv9VQBcURZeloh1",
"__v":0,
"status":200
}

Example:

curl -v -X GET -u user@example.com:123456 https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/requests/support-group-L_OG76RYhR0XFiMf2PK/messages/5c81593adf767b0017d1aa68

Insert multiple messages

POST https://api.pingstreams.com/v3/:project_id/requests/:request_id/messages/multi

This method should be used for mass importing of messages. For common cases, use Send message REST API

Path Parameters

Parameter	Type	Description
project_id	string	The project_id is a unique code assigned to your project when you create it in Pingstreams
request_id	string	The request identifier. Must follow this pattern ‘support-group-UUID’

Headers

Header	Type	Description
Authorization	string	authorization token. Basic Auth or JWT
Content-Type	string	use “application/json” value

Request Body

Field	Type	Description
text	string	the message text
attributes	object	it’s the message custom attributes. Example: attributes = {"custom_attribute1": "value1"}. You can also use attributes to enable advanced features.
type	string	it’s the message type. “text” value for textual message and “image” for sending image message(you must set metadata field). Available values: text (default) and image.
metadata	object	it’s the image properties: src is the absolute source path of the image, width is the image width, height is the image height. Width and height are optional. Example: metadata = { "src": "https://www.pingstreams.com/wp-content/uploads/2018/03/pingstreams-logo.png", "width": 200, "height": 200 }

Response

{
"_id":"5c81593adf767b0017d1aa68",
"updatedAt":"2019-03-07T17:47:38.411Z",
"createdAt":"2019-03-07T17:47:38.411Z",
"sender":"SRbb2PfbSFcgICv9VQBcURZeloh1",
"senderFullname":"Guest",
"recipient":"support-group-L_OG76RYhR0XFiMf2PK",
"text":"hello from api",
"id_project":"5b55e806c93dde00143163dd",
"createdBy":"SRbb2PfbSFcgICv9VQBcURZeloh1",
"__v":0,
"status":200
}

Example of inserting multiple messages:

curl -v -X POST -H 'Content-Type: application/json' -u user@example.com:123456 -d '[{"sender":"bb0d809b-b093-419b-8b48-11a192cc3619","text":"1"},{"sender":"bb0d809b-b093-419b-8b48-11a192cc3619", "text":"2"}]' https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/requests/support-group-1234/messages/multi