NOTE: all requests must be authenticated.

Path	`/api/orgs/{org-id}/conversations/upsert`
Method	`POST`
Response Type	`application/json`

URL Path Parameters

Name	Value
org-id	the UUID of the org in which to create the conversation

Example Request

$ curl \
 -X GET \
 -H "Authorization: Token <auth token value>" \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{"conversation": {… see below …}}' \
 'https://devapi.yapsterchat.com/api/orgs/<org-id>/private-conversations/<from-id>/<to-id>'

A successful response will be a JSON document consisting of the POSTed "conversation" with the addition of an "id" field containing it’s UUID within Yapster.

`POST` Body Parameter

To be sent as application/json:

{
 "conversation": {
 // required
 "name": "conversation title",
 "type": "group",
 "visibility": "group",
 "join_policy": "closed",
 "user_ids": ["<user ID>", "<user ID>", …],
 "group_ids": ["<group ID>", "<group ID>", …],
 // optional
 "client_id": "<unique ID to prevent double posting, in UUID format>",
 "external_uid": "<unique ID to aid retrieval>"
 "conversation_pic_url": "https://example.com/header/image.jpg" "callback": {"url": "https://example.com/callback"}
 }
}

Things to note:

You must specify a "name" (title) for the conversation.
The “type”, “visibility”, and “join_policy” should always be as specified above (other values are a potential future enhancement.)
It is advised to use a "client_id" to guard against double posting if/when a request is resubmitted due to failure. This should be a UUID in standard, RFC 4122, string format, e.g. dd9f962e-72e1-498b-a039-73faa5866d5f.
Specifying an "external_uid" will help you find the conversation again later.
Giving a "conversation_pic_url" will display the corresponding image as a title image on the conversation.
You can address both individual users and groups of users (and any combination thereof.)
The "user_ids" and "group_ids" lists must always be provided—even when not addressing that type of entity (e.g. you must still provide an empty "user_ids" array when only addressing groups.)

Addressing Users

To address individual users in a conversation find their user IDs and provide them as an array under the "user_ids" field when creating the conversation.

Addressing Groups

To address entire groups of users in a conversation find their group IDs and provide them as an array under the "group_ids" field when creating the conversation.

Intersecting Groups

You can address a subset of a group (or groups)—for example “Managers in London”—by providing an intersection rather than the individual group IDs.

A simple intersection (“Managers in London”) would be specified as:

["and", "<managers group ID>", "<london group ID>"]

You can also construct intersections over multiple groups, e.g. “Chefs and Sous-Chefs in Brighton”:

["and", ["or", "<chefs group ID>", "<sous-chefs group ID>"], "<london group ID>"]

Registering a Callback

As shown in the body parameter you may optionally provide a “callback URL” when creating conversations. These URLs will receive, via HTTP POST requests, a copy of any message posted in the conversation.

The format of the callback requests made by Yapster to your registered handler are:

$ curl \
 -X POST
 -H "Content-Type: application/json" \
 -d '<callback POST body>' \
 https://example.com/callback

With the POST body consisting of:

{
 "conversation_message": {
 "org_id": "org UUID",
 "conversation_id": "conversation UUID",
 "id": "message UUID",
 "external_uid": "external UID of message", // if originating from external API client
 "type": "plain",
 "author_id": "message author user UUID",
 "body": "message text",
 "message_pic_url": "https://example.com/image.jpg", // may be null
 "message_video_url": "https://example.com/video.mp4", // may be null
 "media_ref": [], // see below
 "deleted": false, // or true on deletion
 "edited": false, // or true when edited
 "message_time": "ISO-8601 timestamp",
 "updated_at": "ISO-8601 timestamp",
 "history": [{ … previous version of message … }, …], // if the message has “quoted” another:
 "reply_to": {
  "id": "UUID of quoted/replied to message",
  "author_id": "replied-to message author UUID",
  "message_time": "ISO-8601 timestamp",
  "body": "replied-to message body",
  "media_ref": [
    {
      "type": "image", // or "video" or "document"
      "path": "https://example.com/image.jpg"
    },
    …
   ]
  }
 }
}

About those "media_ref"s … if a message contains more than one picture then the "message_pic_url" will be null and there will instead be entries in the "media_ref" array. Unfortunately those entries will be encoded as serialized EDN and so will be strings as in:

{
 "media_ref": ['{:type "image", :path "https://example.com/image.jpg"}'] 
}