Requests

Requests are the means through which your end users (customers) communicate with agents in Pingstreams. Requests can originate from a number of channels, including email, chat, Facebook, WhatsApp or the API. All requests have a core set of properties. Commonly when a request is created via email channel it is also called a ticket in the Pingstreams platform. Instead when a request is created by a chat channel it is also called conversation.

The Request model

Field	Type	Description
id	String	The unique identifier for the request which is given by
request_id	String	A unique identifier for the request which is given to Pingstreams. Follow this pattern ‘support-group-UUID’. It is an external Id, so you must uniquely generate this id and pass it to Pingstreams. For example you can generate this id like this: ‘support-group-af4b54df-3237-4db5-9351’ (using uuid or other UUID generator) or using timestamp like this ‘support-group-TIMESTAMP’
first_text	String	the request first text.
department	Object	the Department model selected for the request.
lead	Object	the Lead model involved in this request.
requester	Object	contains information about the user originated the request. This is a Team model.
participants	Array	The list of the identifier of the teammates or bots who participated in the request.
participatingAgents	Array	The list of the teammates who participated in the request.
participatingBots	Array	The list of the bots who participated in the request.
hasBot	Boolean	Indicates whether a bot is participating in the conversation.
status	Number	The request status: TEMPORARY : 50, UNSERVED : 100, ABANDONED : 150, SERVED : 200, CLOSED : 1000
sourcePage	String	The request source page.
language	String	The request language.
userAgent	String	The user agent.
tags	Array	A list of tags objects associated with the request.
notes	Array	A list of notes objects associated with the request.
rating	Number	The request rating. From 0 to 5.
rating_message	String	The rating message.
waiting_time	Number	Wait time is calculated as duration between the first visitor message in the chat and the first agent message.
transcript	String	The chat transcript.
attributes	Object	The custom attributes which are set for the request.
channel	Object	The channel of the conversation.
createdAt	String	The time (ISO-8601 date string) when the request was created.
first_response_at	String	The time (ISO-8601 date string) when the first answer is given by bot or an agent
updatedAt	String	The time (ISO-8601 date string) when the request was updated.
assigned_at	String	The time (ISO-8601 date string) when the request was assigned to an agent or bot.
first_response_at	String	The time (ISO-8601 date string) when the agent or the bot replies the first time.
closed_at	String	The time (ISO-8601 date string) when the request was closed.
closed_by	String	The unique identifier of the user who closed the request.
createdBy	String	The unique identifier of the row creator
preflight	Boolean	If true the request has been proactively created by the system and the user has not yet sent a message
priority	String	Define the priority of the request. Available values: normal (default), low, hight, urgent.
location	Object	Define the location of the request obtained by a geo search based on the ip address of the client.
ticket_id	String	It is the number that uniquely identifies the request within the project.
snapshot	Object	The snapshot object containing context information (like department, lead, requester, agents, availableAgentsCount) when the the request was created.
id_project	String	The unique identifier of the project

You can use the API to get the request information.

Get all requests

GEThttps://api.pingstreams.com/v3/:project_id/requests

Allows an account to list all the requests for the project.

Path Parameters

Name	Type	Description
project_id	string	the Project Id is a unique code assigned to your project when you create it in Pingstreams.

Query Parameters

Name	Type	Description
sortField	string	what field to sort the results by. default field is createdAt
direction	string	sort direction: 1 (asc) or -1 (desc). Return the results in ascending (1) or descending (-1) order. defaults to desc (-1)
page	number	what page of results to fetch. defaults to first page.
limit	number	specify the maximum number of results to be returned. default is 40 rows
full_text	string	make a fulltext search query
status	string	filter by request status. Values: 100 for unserved requests, 150 for abandoned requests, 1000 for closed requests, “all” to retrieve all statuses. Default value is status < 1000 so it returns all the opened requests. You can also search for multiple statuses separating the statuses with a comma (i.e. 100,200)
start_date	string	filter by date interval. Use the format DD/MM/YYYY to define the start of the interval (i.e. 01/09/2024)
end_date	string	filter by date interval. Use the format DD/MM/YYYY to define the end of the interval (i.e. 30/09/2024)
ticket_id	string	filter by ticket id
dept_id	string	filter by department id
lead	string	filter by lead id
hasBot	boolean	filter by the hasBot field. If hasBot is true, the service returns all requests served by the chatbot, If hasBot is false, the service returns all requests served by a human agent.
tags	string	filter by tag
channel	string	filter by channel name. The channel name can be: “chat21” for chat messages, “email” for inboud ticket email, “form” for ticket created using the Dashboard UI, “whatsapp” for Whatsapp channel, “telegram” for Telegram Channel, “messenger” for Facebook Messenger Channel
snap_lead_email	string	filter by the field email of the lead
snap_lead_lead_id	string	filter by the field lead_id of the lead

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: agent

Response

{
  "perPage": 40,
  "count": 179,
  "requests": [
    {
      "_id": "5c81593adf767b0017d1aa67",
      "updatedAt": "2019-03-07T17:48:05.934Z",
      "createdAt": "2019-03-07T17:47:38.405Z",
      "request_id": "support-group-L_OG76RYhR0XFiMf2PK",
      "requester_id": "5c81593adf767b0017d1aa66",
      "first_text": "first text message",
      "department": "5c34ba232c62730016da250e",
      "sourcePage": "https://www.pingstreams.com",
      "language": "it",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
      "id_project": "5b55e806c93dde00143163dd",
      "createdBy": "5c81593adf767b0017d1aa66",
      "__v": 2,
      "waiting_time": 21709,
      "agents": [
        {
          "__v": 0,
          "createdBy": "5aaa99024c3b110014b478f0",
          "user_available": true,
          "role": "admin",
          "id_user": "5ab0f3fa57066e0014bfd71e",
          "id_project": "5b55e806c93dde00143163dd",
          "createdAt": "2018-10-03T14:40:19.521Z",
          "updatedAt": "2019-03-07T17:47:38.405Z",
          "_id": "5bb4d4d39214830015742b00"
        }
      ],
      "tags": [],
      "notes": [
        {
          "_id": "5e6ba903261616001752b9f4",
          "text": "note 1",
          "createdBy": "5aaa99024c3b110014b478f0",
          "updatedAt": "2020-03-13T15:38:43.880Z",
          "createdAt": "2020-03-13T15:38:43.880Z"
        }
      ],
      "participants": [
        "5aaa99024c3b110014b478f0"
      ],
      "status": 200,
      "lead": {}
    }
  ]
}

Example

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

Get a request by request_id

GEThttps://api.pingstreams.com/v3/:project_id/requests/:request_id

Fetches a request by his or her request_id

Path Parameters

Name	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

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: agent

Response

{
  "_id": "5c81593adf767b0017d1aa67",
  "updatedAt": "2019-03-07T17:48:05.934Z",
  "createdAt": "2019-03-07T17:47:38.405Z",
  "request_id": "support-group-L_OG76RYhR0XFiMf2PK",
  "requester_id": "5c81593adf767b0017d1aa66",
  "first_text": "first text message",
  "department": "5c34ba232c62730016da250e",
  "sourcePage": "https://www.pingstreams.com",
  "language": "it",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
  "id_project": "5b55e806c93dde00143163dd",
  "createdBy": "5c81593adf767b0017d1aa66",
  "__v": 2,
  "waiting_time": 21709,
  "agents": [
    {
      "__v": 0,
      "createdBy": "5aaa99024c3b110014b478f0",
      "user_available": true,
      "role": "admin",
      "id_user": "5ab0f3fa57066e0014bfd71e",
      "id_project": "5b55e806c93dde00143163dd",
      "createdAt": "2018-10-03T14:40:19.521Z",
      "updatedAt": "2019-03-07T17:47:38.405Z",
      "_id": "5bb4d4d39214830015742b00"
    }
  ],
  "tags": [],
  "notes": [
    {
      "_id": "5e6ba903261616001752b9f4",
      "text": "note 1",
      "createdBy": "5aaa99024c3b110014b478f0",
      "updatedAt": "2020-03-13T15:38:43.880Z",
      "createdAt": "2020-03-13T15:38:43.880Z"
    }
  ],
  "participants": [
    "5aaa99024c3b110014b478f0"
  ],
  "status": 200,
  "lead": {}
}

Example

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

Close a request by request_id

PUThttps://api.pingstreams.com/v3/:project_id/requests/:request_id/close

Path Parameters

Name	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

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: agent
Content-Type	string	use “application/json” value

Reopen a request by request_id

PUThttps://api.pingstreams.com/v3/:project_id/requests/:request_id/reopen

Path Parameters

Name	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

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: agent
Content-Type	string	use “application/json” value

Route a request to a department

PUThttps://api.pingstreams.com/v3/:project_id/requests/:request_id/departments

Routes a request to a department.

Path Parameters

Name	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

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: agent
Content-Type	string	use “application/json” value

Request Body

Name	Type	Description
departmentid	string	the department identifier
nobot	boolean	Optional. Default is false. If nobot is true the bot is excluded from the assignment

Update a request by request_id

PATCHhttps://api.pingstreams.com/v3/:project_id/requests/:request_id/

Path Parameters

Name	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

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: agent
Content-Type	string	use “application/json” value

Request Body

Name	Type	Description
first_text	string	the request first text
lead	string	the lead identifier
status	number	the request status
tags	array	the request tags
rating	number	the request rating
rating_message	string	the request rating message
language	string	the request language
sourcePage	string	the request source page

Create a request

POSThttps://api.pingstreams.com/v3/:project_id/requests/:request_id/

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

Path Parameters

Name	Type	Description
project_id	string	the Project Id is a unique code assigned to your project when you create it in Pingstreams.

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: guest
Content-Type	string	use “application/json” value

Request Body

Name	Type	Description
first_text	string	the request first text
request_id	string	the request identifier. If not specified an auto id is generated
language	string	the request language
sourcePage	string	the request source page

Example

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

Rate a request by request_id

PATCHhttps://api.pingstreams.com/v3/:project_id/requests/:request_id/rating

Path Parameters

Name	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

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: guest
Content-Type	string	use “application/json” value

Request Body

Name	Type	Description
rate	number	the request rate from 0 to 5
rate_message	string	the rate message

Example

curl -v -X PATCH -H 'Content-Type:application/json' -u user@example.com:123456 -d '{"rating":5, "rating_message":"Very good"}' https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/requests/support-group-5b55e806c93dde00143163dd/rating

Get all chatbot parameters of a request

GEThttps://api.pingstreams.com/v3/:project_id/requests/:request_id/chatbot/parameters

Allows to obtain all the parameters set by the chatbot during the conversation.

Path Parameters

Name	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_id field. It’s the external request identifier

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: guest
Content-Type	string	use “application/json” value

Example

curl -v -X GET -u user@example.com:password https://api.pingstreams.com/v3/63ad512e70d5ed0012ad6286/requests/support-group-63ad512e70d5ed0012ad6286-82c16d3b10dc4abba2326a5d7611b022/chatbot/parameters