Messaging API - Getting Started

The most common use case for the API is as follows:

A user asks a question.
Directly routes the question to the experts most likely to resolve the question.
An expert adds a response to the question.
Expert and user exchange messages until the question is resolved or needs to be rerouted.

About the Messaging API

Directly offers customers the option to interact with the platform using a set of APIs. This means you can connect to Directly using the technology and user interface of your choice.

Messaging API includes:

A set of REST API endpoints.

Getting started

Get your credentials

Simple Sample Flow

Get an access token (See Authentication) for details.
Ask a new question with POST /questions.
Poll for updates to the question with GET /questions/{uuid} with the lastChecked parameter set. If there is an update (such as a new response) the question will be returned. Otherwise, the method will return a 304.
Accept the new response to the question with POST /responses/{uuid}/accept.
Logout the access token with oauth/logout.

Technical Details

Messaging API is a REST API that uses standard conventions for status codes, responses formats and data types.

Response Format

A response from the REST API will have the following format for all non-authorization endpoints:

{
    "meta": {
        // Meta information about the request: API version, etc
    },
    "data": {
        // Actual data of the request, like question, response, etc.
    },
    "error": { // only present in failed requests (non 200 codes)
        message: "error message"
    }
}

Response Codes

These are the general error codes returned. Check the individual endpoints in the REST API reference docs.

200: Successful request.
201: Successful request and item created. Returned when a user asks a new question or adds a new message.
400: Invalid request. Usually a missing or invalid parameter. Check error section in the response for details.
401: Authentication failed. Check the access token and error section in the response for details.
403: Forbidden. The user doesn't have permissions to perform the request. Check error section in the response for details.
404: Not found.
405: Method not allowed. Making a POST request when you meant a GET?
500: Internal server error. Check error section in the response for details.

Data Types

Encoding:

UTF-8 encoding

Data types:

UUIDs are represented in their 8-4-4-4-12 format. i.e: 123e4567-e89b-12d3-a456-426655440000
Languages are in ISO_639-1. i.e: es, en, fr.
Dates are in ISO-8601 UTC. i.e: 2017-05-18T16:50:38Z

The Conversation Data Model

The core unit of data returned in the REST API is a model of a conversation between a user and one or more experts.

This conversation includes several properties with the question info and current status, and a list of responses and messages. Messages can be authored by the user, experts or by the system.

This is an example of a reduced version of the data model for a question:

{
  "uuid": "123e4567-e89b-12d3-a456-426655440000",
  "conversation": {
    "text": "This is the actual text of the user's question",
    "author": { name: "Original user" },
    "messages": [
      {
        "author": { "name": "System" },
        "body": "Text of the message",
      }
    ],
    "responses": [
      {
        "uuid": "abcd-7890",
        "author": { "name": "Expert name" },
        "isAccepted": false,
        "messages": [
          {
            "author": { "name": "Expert name" },
            "body": "This is the text of an expert message",
          },
          {
            "author": { "name": "Expert name" },
            "body": "This is the another message from the expert",
          },
          {
            "author": { "name": "Expert name" },
            "body": "This is a message from the user",
          }
        ]
      }
    ],
    "unreadMessageCount": 0
  },
  "state": {
    "status": "UNRESOLVED",
    "isAnswered": false,
    "isClosed": false,
    "rerouteStatus": {
      "isRerouted": false
    }
  }
}

You can find the complete version in the REST API reference docs

System Messages

Directly inserts System Messages in the conversation to signal specific events or required actions. Each System Message has a different type property. System Messages are also removed when they are not relevant anymore. Here's a list of them and a brief explanation of each:

NOTIFYING_EXPERTS_SYSTEM_MESSAGE: This is added for new questions and it's removed when an expert engages with the question.
ACCEPTED_RESPONSE_SYSTEM_MESSAGE: Current response has been accepted by the user.
QUESTION_EXPIRED_SYSTEM_MESSAGE: The question has expired with no responses.
QUESTION_CLOSED_SYSTEM_MESSAGE: The question has been closed.
QUESTION_REROUTED_SYSTEM_MESSAGE: The question has been rerouted (usually to agents).
RATE_RESPONSE_SYSTEM_MESSAGE: A system message to prompt the user to rate a response.
CUSTOMER_REROUTE_PROMPT_SYSTEM_MESSAGE: A system message to prompt the user to reroute a question if they are not getting the help they need.
ADD_TESTIMONIAL_SYSTEM_MESSAGE: A system message to prompt the user to add a testimonial.
ADDED_TESTIMONIAL_SYSTEM_MESSAGE: Added after a testimonial has been written.
ACCEPT_RESPONSE_SYSTEM_MESSAGE: A system message to prompt the user to accept the response.
MARK_AS_RESOLVED_MESSAGE: A system message to prompt the user after an expert has marked a response as resolved.
APPROVED_MARK_AS_RESOLVED_MESSAGE: Added when the user accepted the `MARK_AS_RESOLVED_MESSAGE
CONTESTED_MARK_AS_RESOLVED_MESSAGE: Added when the user rejected the `MARK_AS_RESOLVED_MESSAGE