Sending and receiving messages with Pingstreams APIs

Targets

This tutorial will help you to understand how to send and receive “support messages” between Pingstreams End Users and Agents using Pingstreams REST APIs and Webhooks.

Steps

Signup a user on Pingstreams
Anonymous end-user authentication through APIs
Sending messages to a conversation
Receiving new messages notifications using Webhooks

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

Signup

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.

Project Settings

Anonymous end-user authentication through APIs

In this tutorial we will authenticate end-users through anonymous authentication (you can find more info on anonymous authentication here).

All APIs in this tutorial will use the following endpoint:

https://api.pingstreams.com/v3/

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"
  }
}

Sending messages to a conversation

You can send a message using the Send Message API.

To send a message you need to choose a unique request identifier. A request is an object containing all the metadata describing the conversation between end-user and support team.

The request identifier must follow the following pattern:

support-group-<UUID>

curl -v -X POST -H 'Content-Type:application/json' \
-H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XYZ...." \
-d '{"text":"hello from anonym user"}' \
https://api.pingstreams.com/v3/<PROJECT_ID>/requests/support-group-<UUID>/messages

Example with realistic variables instances:

curl -v -X POST -H 'Content-Type:application/json' \
-H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XYZ...." \
-d '{"text":"hello my name is John and I need help"}' \
https://api.pingstreams.com/v3/5e2c35c8f0dbc10017bb3aac/requests/support-group-27df7cbf-3946-4ca4-9b17-dc16114108f8/messages

Looking at the dashboard of your project you will see your first 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).

Receiving new messages notifications using Webhooks

You can subscribe to the messages events sent to a conversation using Webhooks.

You must first create a subscription to an event that points to a url on your server.

In this case we will subscribe to message creation event on a custom url (/test) on requestcatcher.com, a free, beautiful service to debug your webhooks:

curl -v -X POST -H 'Content-Type:application/json' \
-u user@example.com:123456 \
-d '{"event":"message.create", "target":"https://pingstreams.requestcatcher.com/test"}' \
https://api.pingstreams.com/v3/5e2c35c8f0dbc10017bb3aac/subscriptions

The subscription endpoint returns:

{
  "secret": "0fd2a8a1-a3e6-443b-9fe5-49b83612cd72",
  "_id": "5e2c6a24f5b11c00175f1705",
  "target": "https://pingstreams.requestcatcher.com/test",
  "event": "message.create",
  "id_project": "5e2c35c8f0dbc10017bb3aac",
  "createdBy": "5e2c357af0dbc10017bb3aa7",
  "createdAt": "2020-01-25T16:17:40.088Z",
  "updatedAt": "2020-01-25T16:17:40.088Z",
  "__v": 0
}

Now you are notified for each message sent to your Pingstreams project. Now, for example, if the agent sends a message to the end user, your webhook endpoint will be notified with the message payload.

This is the webhook notification with the message payload. You can use this notification to create a copy of all messages sent/received in your project, generate new custom events, communicate in real time on other channels etc.

{
  "timestamp": 1579969429552,
  "payload": {
    "type": "text",
    "status": 200,
    "_id": "5e2c6b958c9612001716bede",
    "sender": "5e2c357af0dbc10017bb3aa7",
    "senderFullname": "demo demo",
    "recipient": "support-group-27df7cbf-3946-4ca4-9b17-dc16114108f10",
    "text": "Hi I'm Rosy. How can help you?",
    "id_project": "5e2c35c8f0dbc10017bb3aac",
    "createdBy": "5e2c357af0dbc10017bb3aa7",
    "metadata": "",
    "attributes": {
      "client": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
      "sourcePage": "https://api.pingstreams.com/v3/chat/index.html",
      "userEmail": "user@example.com",
      "userFullname": "aaa22 aaa22"
    },
    "createdAt": "2020-01-25T16:23:49.394Z",
    "updatedAt": "2020-01-25T16:23:49.394Z",
    "__v": 0,
    "request": {
      // ... request details
    }
  },
  "hook": {
    "_id": "5e2c6a24f5b11c00175f1705",
    "target": "https://pingstreams.requestcatcher.com/test",
    "event": "message.create",
    "id_project": "5e2c35c8f0dbc10017bb3aac",
    "createdBy": "5e2c357af0dbc10017bb3aa7",
    "createdAt": "2020-01-25T16:17:40.088Z",
    "updatedAt": "2020-01-25T16:17:40.088Z",
    "__v": 0
  }
}

Sending and receiving messages with Pingstreams APIs

Targets

Steps

Signup on Pingstreams

Anonymous end-user authentication through APIs

Sending messages to a conversation

Receiving new messages notifications using Webhooks