Direct Messaging

Direct Messaging

NOTE: all requests must be authenticated.

Sending a direct message to another user is no different to sending a message to any other conversation. The only requirement is that you know the conversation ID.

Follow the instructions below to retrieve the conversation ID for the direct messaging conversation between your account and another user and then use that ID when sending a message.

Required Record Details

In order to directly message another user you need:

• The org-id of the organization in which you both have accounts.

  See: Finding Orgs

• Your user-id.

  See: Retrieving Your Authenticated User Details

• Their user-id.

  See: Finding Users

Finding the Conversation

To directly message a user you must first find and/or create a private conversation between you:

Path	/api/orgs/{org-id}/private-conversations/{from-id}/{to-id}
Method	GET
Response Type	application/json

URL Path Parameters

Name	Value
org-id	the UUID of the org in which you are messaging the user
from-id	your user ID
to-id	the recipients user ID

Note: which user ID is used for the from/to parameter doesn’t matter—only a single direct conversation can ever exist between two users and looking up/creating the conversation from-you/to-them or from-them/to-you will always return the same record.

Example Request

$ curl \
  -X GET \
  -H "Authorization: Token <auth token value>" \
  -H 'Accept: application/json' \
  'https://devapi.yapsterchat.com/api/orgs/<org-id>/private-conversations/<from-id>/<to-id>'

A successful response will be a JSON document consisting of:

{
 "conversation": {
   "org_id": "<org UUID>",
   "id": "<conversation UUID>",
   // … other conversation details
 },
 …
}

Note: in addition to returning the "conversation" the response will include a "conversation_participant" record which encapsulates details related to your interaction with the conversation.

Now that you’ve identified the conversation you can proceed to send the other user a message in it.