Chatbots

The Bot model

Field	Type	Description
`id`	String	The unique identifier for the bot which is given by Pingstreams.
`name`	String	The bot name.
`id_project`	String	The unique identifier of the project
`type`	String	The bot type. Permitted values: internal, external.
`secret`	String	The bot secret token used for JWT authentication.
`createdBy`	String	The unique identifier of the row creator
`description`	String	(Optional) The bot description.
`url`	String	(Optional) The bot external endpoint address
`webhook_url`	String	(Optional)
`webhook_enabled`	Boolean	(Optional)
`trashed`	Boolean	(Optional) The bot status.
`attributes`	Object	(Optional) The custom attributes which are set for the bot.
`language`	String	(Optional) The bot language.
`createdAt`	String	(Optional) The time when the bot was created.
`public`	Boolean	(Optional) The sharing status of the bot. Default false.
`updatedAt`	String	(Optional) The time when the bot was updated.

Get all bots

GET https://api.pingstreams.com/v3/:project_id/bots

Allows an account to list all the bots of the project.

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.

Headers

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

Response

[
{
"_id":"5be9b2ecc72a050015e14951",
"updatedAt":"2018-11-12T17:05:50.616Z",
"createdAt":"2018-11-12T17:05:48.544Z",
"name":"bot1",
"id_project":"5b55e806c93dde00143163dd",
"trashed":false,
"createdBy":"5ab0f3fa57066e0014bfd71e",
"__v":0,
"external":false
},
{
"_id":"5ce265596438e40017e3610d",
"updatedAt":"2019-05-20T08:29:14.524Z",
"createdAt":"2019-05-20T08:29:13.286Z",
"name":"bot2",
"id_project":"5b55e806c93dde00143163dd",
"trashed":false,
"createdBy":"5ab0f3fa57066e0014bfd71e",
"__v":0,
"external":false
}
]

Example

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

Get a bot by id

GET https://api.pingstreams.com/v3/:project_id/bots/:id

Allows an account to get a bot of the project.

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.
`id`	string	The bot identifier

Headers

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

Response

{
"_id":"5be9b2ecc72a050015e14951",
"updatedAt":"2018-11-12T17:05:50.616Z",
"createdAt":"2018-11-12T17:05:48.544Z",
"name":"bot1",
"id_project":"5b55e806c93dde00143163dd",
"trashed":false,
"createdBy":"5ab0f3fa57066e0014bfd71e",
"__v":0,
"external":false
}

Example

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

Export a bot in JSON format

GET https://api.pingstreams.com/v3/:project_id/bots/exportjson/:id

Allows an accont to export the bot in json format

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
`id`	string	The bot identifier

Query Parameters

Parameter	Type	Description
`intentsOnly`	boolean	(Optional) if TRUE will be exported only the intents (faqs)

Headers

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

Response

{"webhook_enabled":false,"language":"en","name":"bot1","intents":[{"webhook_enabled":false,"enabled":true,"question":"\start","answer":"Hello","intent_display_name":"start","language":"en"}]}

Example

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

Create a new bot

POST https://api.pingstreams.com/v3/:project_id/bots

Allows to add more bots.

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

Headers

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

Request Body

Field	Type	Description
`name`	string	The bot name
`description`	string	The bot description
`language`	string	The bot language with two-letter ISO 639-1 code.
`webhook_enabled`	string	Enable the webhook fullfillment endpoint
`template`	string	If internal type is used you can specify the template used to create the faqs. Supported values : blank, handoff, example. Example is the default value. Blank is a basic chatbot with only start e defaultFallback intents. Handoff is like the basic chatbot with the Agent handoff intent. Example is a chatbot with a showcase of the main features.
`type`	string	Supported type values are: “internal”, “external”. Default is “internal”. With internal value the standard pingstreams bot engine is used. With external you can create your own chatbot engine specifing the url parameter.
`url`	string	The external chatbot endpoint

Response

{
"_id":"5be9b2ecc72a050015e14951",
"updatedAt":"2018-11-12T17:05:50.616Z",
"createdAt":"2018-11-12T17:05:48.544Z",
"name":"bot1",
"id_project":"5b55e806c93dde00143163dd",
"trashed":false,
"createdBy":"5ab0f3fa57066e0014bfd71e",
"__v":0,
"external":false
}

Example:

curl -v -X POST -H 'Content-Type: application/json' -u user@example.com:123456 -d '{"name":"bot1"}' https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/bots

Fork a bot

POST https://api.pingstreams.com/v3/:project_id/bots/fork/:id

Allows to fork an existing bot.

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
`id`	string	The bot identifier

Query Parameters

Parameter	Type	Description
`public`	string	The sharing status of the bot. Permitted values: true \| false
`projectid`	string	The id of the project where wants to fork the bot

Headers

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

Response

{
"message":"Chatbot forked successfully",
"bot_id":"5ab0f3fa57066e0014bf777e"
}

Example:

curl -v -X PUT -H 'Content-Type: application/json' -u user@example.com:123456 https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/bots/fork/5be9b2ecc72a050015e14951?public=false&projectid=5b55e806c93dde0014316e33

Import whole bot from JSON

POST https://api.pingstreams.com/v3/:project_id/bots/importjson/:id

Allows to import the bot informations and intents from a JSON file.

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
`id`	string	the bot identifier (on which perform import) (is null with create option)

Query Parameters

Parameter	Type	Description
`create`	string	Allows to create a chatbot before importing Permitted values: true \| false \| null
`replace`	string	(BETA) Allows you to clean the chatbot (all its intents) before importing Permitted values: true \| false \| null
`overwrite`	string	Choose whether to replace intents with the same intent_display_name with the imported ones. If false or null Old intents with the same intent_display_name will not be overwritten. Permitted values: true \| false \| null

Headers

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

Request Body

Field	Type	Description
`uploadFile`	json	The JSON file that contains data.

Response

{
"_id":"5be9b2ecc72a050015e14951",
"updatedAt":"2018-11-12T17:05:50.616Z",
"createdAt":"2018-11-12T17:05:48.544Z",
"name":"bot1",
"id_project":"5b55e806c93dde00143163dd",
"trashed":false,
"createdBy":"5ab0f3fa57066e0014bfd71e",
"__v":0,
"external":false
}

Example:

curl -v -X POST -H 'Content-Type: application/json' -u user@example.com:123456 -d "@path_to_file/bot.json" https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/bots/importjson/5be9b2ecc72a050015e14951

Update a bot

PUT https://api.pingstreams.com/v3/:project_id/bots/:id

Allows to update a bot.

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
`id`	string	The bot identifier

Headers

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

Request Body

Field	Type	Description
`name`	string	The bot name
`url`	string	The bot external endpoint
`description`	string	The bot description
`language`	string	The bot language with two-letter ISO 639-1 code.
`webhook_enabled`	string	Enable the webhook fullfillment endpoint
`type`	string	Supported type values are: “internal”, “external”. Default is “internal”. With internal value the standard pingstreams bot engine is used. With external you can create your own chatbot engine specifing the url parameter.

Response

{
"_id":"5be9b2ecc72a050015e14951",
"updatedAt":"2018-11-12T17:05:50.616Z",
"createdAt":"2018-11-12T17:05:48.544Z",
"name":"bot1",
"id_project":"5b55e806c93dde00143163dd",
"trashed":false,
"createdBy":"5ab0f3fa57066e0014bfd71e",
"__v":0,
"external":false
}

Example:

curl -v -X PUT -H 'Content-Type: application/json' -u user@example.com:123456 -d '{"name":"bot1"}' https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/bots/5be9b2ecc72a050015e14951

Delete a bot

DELETE https://api.pingstreams.com/v3/:project_id/bots/:id

Allows to delete a bot.

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
`id`	string	The bot identifier

Headers

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

Response

{
"_id":"5be9b2ecc72a050015e14951",
"updatedAt":"2018-11-12T17:05:50.616Z",
"createdAt":"2018-11-12T17:05:48.544Z",
"name":"bot1",
"id_project":"5b55e806c93dde00143163dd",
"trashed":false,
"createdBy":"5ab0f3fa57066e0014bfd71e",
"__v":0,
"external":false
}

Example:

curl -v -X DELETE -H 'Content-Type: application/json' -u user@example.com:123456 https://api.pingstreams.com/v3/5b55e806c93dde00143163dd/bots/5be9b2ecc72a050015e14951