NOTE: all requests must be authenticated.

Required Record Details

In order to send a message to a conversation you need:

The org id of the organization in the conversation exists.
See: Finding Orgs
The conversation id to which you wish to post.
See: Finding Conversations
The user_ids of any users you wish to @mention.
See: Finding Users

Constructing Your Message

Messages are constructed as plain text with no special formatting applied. Any links included in the text will be marked up (and clickable) when displayed and UTF8 is fully supported so feel free light a 🔥 or spread some ❤️️ with emojis.

Including Images

There are two options for including images in messages:

Specify a single image as a "message_pic_url".
Include a "media_ref"s array detailing the paths to multiple images.
(The details of populating this field can be found further on in this document.)

Including Videos

There are two options for including videos in messages:

Include a single video as a "message_video_url".
Include a Youtube or Vimeo link within the message text.
Video URLs from these services will be extracted and a corresponding video player will be embedded in the message when it is displayed within the Yapster client.
This should be your preferred means of including videos.

`@mention`ing Users

To @mention a user (and have them receive a push notification for your message) you must find their user ID and then include the string @<user-id> within the body of your message.

Posting the Message

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

URL Path Parameters

Name	Value
org-id	the UUID of the org in which the conversation exists
conversation-id	the UUID of the conversation to post a message in

Example Request

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

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

`POST` Body Parameter

To be sent as application/json:

{
 // required
 "body": "message text", // may be empty
 "message_pic_url": "https://example.com/image.jpg", // may be null
 "message_video_url": "", // may be null
 "media_ref": [], // see note below
 // optional
 "client_id": "<unique ID to prevent double posting, in UUID format>",
 "external_uid": "<unique ID to identify your own messages in callbacks>"
}

If using a "client_id" to uniquely identify the message (and prevent potential double posting) please ensure that the ID is a UUID conforming to the RFC 4122 standard text representation, e.g. dd9f962e-72e1-498b-a039-73faa5866d5f.

About that "media_ref" field … if you want to attach more than one image to a message you need to populate the "media_ref" rather than specifying a "message_pic_url". Unfortunately entries inside the array need to be encoded as serialized EDN and so should be strings as in:

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