WeSeeDo WeSeeDo Direct API

API reference on SwaggerHub

Introduction

The WeSeeDo Direct API helps you to implement a one-way, safe and live visual connection in your existing software packages. It enables you to watch and assist customers during a telephone conversation, while the telephone connection remains.

You can integrate the WeSeeDo Direct API within your existing company processes and your own applications using OAuth2. The WeSeeDo Direct API does not store data.

Conceptual model

WeSeeDo Direct Conceptual Model

Definitions

Agent

A person working for an agency or company who deals with customer queries.

Participant

A person or customer who reports incidents to the agent.

API workflow

WeSeeDo Direct API Workflow

Automatic agent login workflow

WeSeeDo Direct Agent auto login workflow

Prerequirements

Participant

A mobile device with:

  • A camera.
  • An adequate internet connection, minimum 3G or wifi.
  • A WebRTC supported browser.

Agent

  • A WebRTC supported browser, preferably Google Chrome.

Features and constraints

Features

  • One-way visual connection.
  • Direct image of location/situation on site.
  • Existing telephone calls will continue to work.

  • Optional: agents can take pictures of location or situation on site in the web browser.

  • Optional: agents can chat with participants.

Getting started

Authentication

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

If you are using cURL for Windows, please use the command below instead.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authentication service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

How to...

Start a WeSeeDo Direct video call

Follow these steps to schedule your first WeSeeDo Direct video call:

  1. Get an access token.
  2. Create an agent user.
  3. Create a meeting on behalf of this agent.
  4. Send SMS to participant.
  5. Log in agent automatically (optional).

Get an access token

To perform actions on the API, you need to authenticate using your OAuth 2.0 credentials. See Authentication.

Create an agent user

Send a POST request to the /api/user endpoint with the details of the user:

{
  "first_name": "John",
  "last_name": "Doe",
  "role": "agent",
  "email": "john.doe@weseedo.nl",
  "password": "JohnDoePassWord#123"
  "locale": "nl",
}

The server will provide a response similar to the object below:

{
  "success": true,
  "result": {
    "id": "THE_ID_OF_YOUR_USER_HERE",
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "john.doe@weseedo.nl",
    "company": {
      "id": "5d..c3",
      "name": "WeSeeDo Demo Company B.V."
    },
    "created_at": "2019-01-01T00:00:00.000Z",
    "role": "agent",
    "locale": "nl"
  }
}

Note: The id of the newly created agent user is the user id of the agent that you will use in subsequent requests.

The agent user can now immediately log into the user interface:

Create a meeting on behalf of this agent

Now that you have created the agent user, you can use it to schedule a WeSeeDo Direct call. Send a POST request to the /api/meeting endpoint.

{
  "agent": "Put the ID of the agent user that you created in the previous step here"
  "participant": “0612312312”
}

The server will provide a response similar to the object below:

{
  "success": true,
  "result": {
    "id": "THE_ID_OF_THE_MEETING_HERE",
    "room_id": "9XT...3cX",
    "room_password": "FBJ...A0a",
    "duration": 0,
    "room_available_from": 1568827158,
    "room_available_till": 1569431958,
    "participants": [
      {
        "username": "agent.5d8...45c",
        "name": "Test Agent",
        "id": "5d8...463",
        "user": "5d8...45c",
        "email": "test_agent@weseedo.nl"
      },
      {
        "username": "visitor.qBSnqvFI9TSEsSZA",
        "name": "0612312312",
        "id": "THE_ID_OF_THE_PARTICIPANT_HERE",
        "hash": "A_HASHED_TOKEN_FOR_THE_PARTICIPANT (for example: 4AWLhxRfOgsK0xBC5MRVHZVuELL964zu_mwUwyXwsDEGW07oy4XLiSqtsdvj0QhWp)"
      }
    ]
  }
}

Note: Theid and hash from the participants list (the first one is the agent, the second one is the participant).

Send SMS to participant

Now that the meeting is created, create a SMS containing a secure link and send it to the participant. Send a POST request to the /api/sms endpoint.

{
  "participant": "REPLACE_WITH_THE_ID_OF_THE_PARTICIPANT_FROM_THE_PREVIOUS_REQUEST",
  "body": "Click on the link and click 'Allow'.  https://sandbox-direct.weseedo.nl/client.html?id=REPLACE_WITH_THE_HASHED_TOKEN_FOR_THE_PARTICIPANT_FROM_THE_PREVIOUS_REQUEST"
}

The server will provide the following response:

{
  "result": true
}

A text message is sent to the participant's smartphone. The participant needs to click on the secure link and allow access to the camera of the phone. The video will start streaming immediately to the agent.

Log in agent automatically (optional)

After creation of the agent user, they can log into the user interface using their username and password combination. It is also possible to automatically log in an agent to the application.

Send a GET request to /api/autologin endpoint with the email address of the agent in the HTTP header:

-H 'company_email: firstname.lastname@company.com'

The server provides a Redirect URL, which allows the agent to log in to the portal:

{

    "url": "https://sandbox-direct.weseedo.nl/login/aHgW5FupTeDYLIA6q1IHkqfDaB4Tnqq14hb5StqqWlNsiTarvMTA6aZboBZAB0u9fRwE6QBDy5dgfhuTf0SonGCX1YHqWZu6OLHyZIvQXfSFT2Hqazv2JrL4rSxLmDppDh3uBH6FAvDBCHJDpMi1K2MU3WGHOgsVT1U0A5IlN2lWhJug3hFqLWEdfDvTmuPjX7CG1pSNkSLhFWQGqItnw6KsdBhZJzajdjSAJamBZx1Ofe6WrR947kcTeCluVfrQ"

}

URLs to Sandbox and production site

  • Sandbox: https://sandbox-direct.weseedo.nl/login/REPLACE_WITH_ACCESS_TOKEN_OF_AGENT.
  • Production: https://login-direct.weseedo.nl/login/REPLACE_WITH_ACCESS_TOKEN_OF_AGENT.

When using the URLs mentioned above, the agent will automatically be logged in and able to use the application.

The user interface also provides the ability to create meetings.

If you want to prevent the agent from creating meetings that way and only want to log in the agent for a specific WeSeeDo Direct session,do the following: After creating a new meeting, send the Redirect URL with an added /1 to the participant.

For example:

https://sandbox-direct.weseedo.nl/login/aHgW5FupTeDYLIA6q1IHkqfDaB4Tnqq14hb5StqqWlNsiTarvMTA6aZboBZAB0u9fRwE6QBDy5dgfhuTf0SonGCX1YHqWZu6OLHyZIvQXfSFT2Hqazv2JrL4rSxLmDppDh3uBH6FAvDBCHJDpMi1K2MU3WGHOgsVT1U0A5IlN2lWhJug3hFqLWEdfDvTmuPjX7CG1pSNkSLhFWQGqItnw6KsdBhZJzajdjSAJamBZx1Ofe6WrR947kcTeCluVfrQ/1

URLs to Sandbox and production site

  • Sandbox: https://sandbox-direct.weseedo.nl/login/REPLACE_WITH_ACCESS_TOKEN_OF_AGENT/1.
  • Production: https://login-direct.weseedo.nl/login/REPLACE_WITH_ACCESS_TOKEN_OF_AGENT/1.

The Redirect URLs send the participant to a limited web interface, which only allows to:

  • Wait for a participant to click the link in the SMS.
  • Perform the video call.
  • When the call ends, the agent is redirected to a page indicating that the call has ended. The normal user interface to schedule meetings will not be accessible to the agent.

Return codes

Code   Description
200   Success
201   Created
202   Accepted
302   Found. Link in location header
400   Bad request
401   Unauthorized
403   Forbidden
404   Not found
405   Method not allowed
412   Precondition failed
429   Too many requests
500   Internal server error
502   Bad gateway
503   Service unavailable