NOTE: all requests must be authenticated.
Required Record Details
In order to send a message to a conversation you need:
The org
idof the organization in the conversation exists.See: Finding Orgs
The conversation
idto which you wish to post.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.
@mentioning 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 | |
Method |
|
Response Type |
|
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"}']
}