Import multiple messages into Pingstreams using REST APIs from third party app

Targets

This tutorial will help you to understand how to insert multiple messages into Pingstreams using REST API from third party app. Suppose you have an application (ex. a chatbot framework or a customer support system) and you want to connect it with Pingstreams. For example suppose you have a chatbot software that automatically serves the users (via a widget or others channels) but at some point you want to forward the chat to Pingstreams so that the agents (and no longer the chatbot) serve the request.

Steps

1. Signup a user on Pingstreams
2. Anonymous end-user authentication through APIs
3. Creating the conversation (request)
4. Sending messages to a conversation

Signup on Pingstreams

To use Pingstreams APIs is mandatory to signup a new user on our beta environment available on https://panel.pingstreams.com/v3/dashboard

After signup please follow the proposed wizard to create your first Pingstreams project.

Get the PROJECT_ID of the created project under Project Settings menu. We will use this later.

Anonymous end-user authentication through APIs

In this tutorial we will authenticate end-users through Anonymous authentication REST API. We will do an anonymous authentication in order to get the id of the user (requester) who will create the conversation (next paragraph).

curl -v -X POST -H 'Content-Type:application/json' \
-d '{"id_project":"5e2c35c8f0dbc10017bb3aac", "firstname":"John"}' \
https://api.pingstreams.com/v3/auth/signinAnonymously

This will reply with the JWT token that we’ll use to send our first message:

{
  "success": true,
  "token": "JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XYZ....",
  "user": {
    "_id": "fc43a0e1-ba85-404e-9a44-bf0050330898",
    "firstname": "John",
    "id": "fc43a0e1-ba85-404e-9a44-bf0050330898",
    "fullName": "John"
  }
}

Creating the conversation (request)

Now let’s use Create a conversation REST API by setting mainly four parameters:

• YOUR_ADMIN_EMAIL and PASSWORD: use your admin credentials here
• SENDER: the anonymous user id created with the previous step
• FIRST_MESSAGE: this text is used to summarize the conversation subject. Normally this is the first message send by the user requester
• PROJECT_ID: your project id

curl -v -X POST -H 'Content-Type:application/json' \
-u YOUR_ADMIN_EMAIL:PASSWORD -d '{"sender":"SENDER", "first_text":"FIRST_MESSAGE"}' \
https://api.pingstreams.com/v3/PROJECT_ID/requests/

Example:

curl -v -X POST -H 'Content-Type:application/json' \
-u user@example.com:xyz -d '{"sender":"fc43a0e1-ba85-404e-9a44-bf0050330898", "first_text":"How can i restore my password"}' \
https://api.pingstreams.com/v3/5e2c35c8f0dbc10017bb3aac/requests/

You will get a response like this:

{
  "_id": "6346cbed38c343d545cf8092",
  "request_id": "support-group-5e2c35c8f0dbc10017bb3aac-8e40526e6dfb4450a572cd4ede01f464"
  // ... other fields
}

Now an empty (without message) conversation is created. Pay attention to the request_id field for the next paragraph.

Sending messages to a conversation

Let us use Insert multiple messages REST API to import the messages. We need the following parameters:

• request_id: the unique request identifier generated by the previous endpoint call
• the admin credentials
• An array of messages where:
  • text: is the message text
  • sender: is the user identifier of the user who send the message
  • attributes.clienttimestamp: use this property to force the message timestamp in milliseconds

curl -v -X POST -H 'Content-Type:application/json' \
-u YOUR_ADMIN_EMAIL:PASSWORD \
-d '[{"sender":"bb0d809b-b093-419b-8b48-11a192cc3619","text":"How can i restore my password", "attributes":{"clienttimestamp":1665584701710}},{"sender":"chatbot1", "text":"You can find it here https://pingstreams.com", "attributes":{"clienttimestamp":1665584701711}}]' \
https://api.pingstreams.com/v3/5e2c35c8f0dbc10017bb3aac/requests/support-group-5e2c35c8f0dbc10017bb3aac-8e40526e6dfb4450a572cd4ede01f464/messages/multi

Looking at the dashboard of your project you will see your conversation in the Requests panel. The requests are updated in real time, so you don’t have to manually update the Requests’ page. If you left unchanged all the default settings, the request will be assigned to you (make sure you are “available”, looking in the lower right corner of your profile image in the left menu panel).

The agent (you) can now see the same conversation in the agent chat (first option of the menu panel will open the desktop chat).