1. Reference
  2. Web API
  3. Conversations

Conversations

The Conversations API has methods for creating, and managing conversations. A conversation is a non-contextual chat app, and is mainly used by the Messenger building block.

Create conversation

Creates a new conversation with the specified members. When no type is specified the following logic is applied to decide the type of conversation to create.

  • If a name is specified, or member count is more than one, a chat room is created.
  • If only one member is specified, a private chat is created. If there is an existing chat between the creator and member, that instance is returned instead of creating a new chat.
POST /api/conversations
Body parameters
members array of strings required

User identifiers (id or uid) of conversation members.

name string

Room name.

type string

Type of conversation to create (private_chat, chat_room or bot_chat). Automatically inferred when not specified.

Example request
curl https://{WEAVY-SERVER}/api/conversations
-H "Authorization: Bearer {ACCESS-TOKEN}"
--json "{ 'members': [ 'bugs-bunny' ] }"

curl https://{WEAVY-SERVER}/api/conversations
-H "Authorization: Bearer {ACCESS-TOKEN}"
--json "{ 'members': ['bugs-bunny', 'daffy-duck', 14], 'name': 'Acme'  }"
Response codes

201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
422 Validation Failed

Response schema
{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "created_by_id": "integer",
  "created_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "modified_at": "string",
  "modified_by_id": "integer",
  "modified_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "permissions": [
    "string"
  ],
  "last_message_id": "integer",
  "last_message": {
    "id": "integer",
    "app_id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "attachment_count": "integer",
    "attachments": [
      "object"
    ],
    "embed_id": "integer",
    "meeting_id": "integer",
    "option_count": "integer",
    "options": [
      "object"
    ],
    "reactions": [
      "object"
    ],
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "created_by_id": "integer",
    "modified_at": "string",
    "modified_by_id": "integer",
    "is_trashed": "boolean"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

Get conversation

Get conversation.

GET /api/conversations/{id}
Path parameters
id integer required

Id of the conversation to return.

Query parameters
trashed boolean

true to return conversation even if trashed, otherwise false.

Example request
curl https://{WEAVY-SERVER}/api/conversations/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

200 Success
401 Unauthorized
404 Not Found

Response schema
{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "created_by_id": "integer",
  "created_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "modified_at": "string",
  "modified_by_id": "integer",
  "modified_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "permissions": [
    "string"
  ],
  "last_message_id": "integer",
  "last_message": {
    "id": "integer",
    "app_id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "attachment_count": "integer",
    "attachments": [
      "object"
    ],
    "embed_id": "integer",
    "meeting_id": "integer",
    "option_count": "integer",
    "options": [
      "object"
    ],
    "reactions": [
      "object"
    ],
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "created_by_id": "integer",
    "modified_at": "string",
    "modified_by_id": "integer",
    "is_trashed": "boolean"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

List conversations

List conversations for the authenticated user.

GET /api/conversations
Query parameters
member string

User identifier (id or uid). Used to return conversations where specified user is member.

unread boolean

true lists unread conversations, false list read conversations and null lists all conversations; default is null.

type array of strings

Guids of app types to list. Can be used to return only conversations of a specified type, e.g. chat rooms. When not specied all types of conversations are returned.

q string

A query used to find matching items.

tag string

List items with the specified tag.

trashed boolean

Indicates whether trashed items should be listed (default is false). Specify null to return both trashed and non-trashed items.

order_by string

Specifies the sort order and direction for the listing, e.g. "name" or "name+desc"

top integer

Maximum number of items to return in the listing. Should be a value between 1 and 100. Default is 25.

skip integer

The number of items to skip. Used together with top to return a specific range of items (for pagination).

count_only boolean

true to only return the number of matching items; when this is specified the response will only contain the count property.

Example request
curl https://{WEAVY-SERVER}/api/conversations?top=20
-H "Authorization: Bearer {ACCESS-TOKEN}"
Response codes

200 Success
401 Unauthorized

Response schema
{
  "data": [
    {
      "id": "integer",
      "type": "string",
      "uid": "string",
      "access": "string",
      "directory_id": "integer",
      "display_name": "string",
      "name": "string",
      "description": "string",
      "archive_url": "string",
      "avatar_url": "string",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "created_at": "string",
      "created_by_id": "integer",
      "modified_at": "string",
      "modified_by_id": "integer",
      "permissions": [
        "string"
      ],
      "last_message_id": "integer",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "is_trashed": "boolean",
      "is_pinned": "boolean",
      "is_unread": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Indicate typing

Indicate that the authenticated user is typing a message in a conversation.

PUT /api/conversations/{id}/typing
Path parameters
id integer required

Conversation (app) id.

Example request
curl -X PUT https://{WEAVY_SERVER}/api/conversations/1/typing
-H "Authorization: Bearer {ACCESS-TOKEN}"
Response codes

204 No Content

Count unread conversations

Get number of unread conversations for the authenticated user (grouped by conversation type).

GET /api/conversations/badge
Example request
curl https://{WEAVY-SERVER}/api/conversations/badge
-H "Authorization: Bearer {ACCESS-TOKEN}"
Response codes

200 Success

Response schema
{
  "private": "integer",
  "rooms": "integer",
  "bots": "integer"
}

Mark as read

Updates the conversation read marker for the authenticated user.

PUT /api/conversations/{id}/mark
Path parameters
id integer required

Conversation (app) id.

Query parameters
message_id integer

Optional id of last seen message, when not specified the entire conversation is marked as read.

Example request
curl -X PUT https://{WEAVY_SERVER}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"
Response codes

200 Success
401 Unauthorized
404 Not Found

Response schema
{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "created_by_id": "integer",
  "created_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "modified_at": "string",
  "modified_by_id": "integer",
  "modified_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "permissions": [
    "string"
  ],
  "last_message_id": "integer",
  "last_message": {
    "id": "integer",
    "app_id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "attachment_count": "integer",
    "attachments": [
      "object"
    ],
    "embed_id": "integer",
    "meeting_id": "integer",
    "option_count": "integer",
    "options": [
      "object"
    ],
    "reactions": [
      "object"
    ],
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "created_by_id": "integer",
    "modified_at": "string",
    "modified_by_id": "integer",
    "is_trashed": "boolean"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

Mark as unread

Mark a conversation as unread, i.e remove the conversation read marker.

DELETE /api/conversations/{id}/mark
Path parameters
id integer required

Conversation (app) id.

Example request
curl -X DELETE https://{WEAVY_SERVER}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"
Response codes

200 Success
401 Unauthorized
404 Not Found

Response schema
{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "created_by_id": "integer",
  "created_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "modified_at": "string",
  "modified_by_id": "integer",
  "modified_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "permissions": [
    "string"
  ],
  "last_message_id": "integer",
  "last_message": {
    "id": "integer",
    "app_id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "attachment_count": "integer",
    "attachments": [
      "object"
    ],
    "embed_id": "integer",
    "meeting_id": "integer",
    "option_count": "integer",
    "options": [
      "object"
    ],
    "reactions": [
      "object"
    ],
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "created_by_id": "integer",
    "modified_at": "string",
    "modified_by_id": "integer",
    "is_trashed": "boolean"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

Pin conversation

Pin a conversation.

PUT /api/conversations/{id}/pin
Path parameters
id integer required

Conversation (app) id.

Example request
curl -X PUT https://{WEAVY_SERVER}/api/conversations/1/pin
-H "Authorization: Bearer {ACCESS-TOKEN}"
Response codes

200 Success
401 Unauthorized
404 Not Found

Response schema
{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "created_by_id": "integer",
  "created_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "modified_at": "string",
  "modified_by_id": "integer",
  "modified_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "permissions": [
    "string"
  ],
  "last_message_id": "integer",
  "last_message": {
    "id": "integer",
    "app_id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "attachment_count": "integer",
    "attachments": [
      "object"
    ],
    "embed_id": "integer",
    "meeting_id": "integer",
    "option_count": "integer",
    "options": [
      "object"
    ],
    "reactions": [
      "object"
    ],
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "created_by_id": "integer",
    "modified_at": "string",
    "modified_by_id": "integer",
    "is_trashed": "boolean"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

Unpin conversation

Unpin a conversation.

DELETE /api/conversations/{id}/pin
Path parameters
id integer required

Conversation (app) id.

Example request
curl -X DELETE https://{WEAVY_SERVER}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"
Response codes

200 Success
401 Unauthorized
404 Not Found

Response schema
{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "created_by_id": "integer",
  "created_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "modified_at": "string",
  "modified_by_id": "integer",
  "modified_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "permissions": [
    "string"
  ],
  "last_message_id": "integer",
  "last_message": {
    "id": "integer",
    "app_id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "attachment_count": "integer",
    "attachments": [
      "object"
    ],
    "embed_id": "integer",
    "meeting_id": "integer",
    "option_count": "integer",
    "options": [
      "object"
    ],
    "reactions": [
      "object"
    ],
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "created_by_id": "integer",
    "modified_at": "string",
    "modified_by_id": "integer",
    "is_trashed": "boolean"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

Set as delivered

Updates the conversation delivery status for the authenticated user.

PUT /api/conversations/{id}/delivered
Path parameters
id integer required

Conversation (app) id.

Example request
curl -X PUT https://{WEAVY_SERVER}/api/conversations/1/delivered
-H "Authorization: Bearer {ACCESS-TOKEN}"
Response codes

200 Success
401 Unauthorized
404 Not Found

Response schema
{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "created_by_id": "integer",
  "created_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "modified_at": "string",
  "modified_by_id": "integer",
  "modified_by": {
    "id": "integer",
    "uid": "string",
    "display_name": "string",
    "email": "string",
    "given_name": "string",
    "middle_name": "string",
    "name": "string",
    "family_name": "string",
    "nickname": "string",
    "phone_number": "string",
    "comment": "string",
    "directory_id": "integer",
    "picture_id": "integer",
    "avatar_url": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "presence": "string",
    "created_at": "string",
    "modified_at": "string",
    "is_bot": "boolean",
    "is_suspended": "boolean",
    "is_trashed": "boolean"
  },
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "permissions": [
    "string"
  ],
  "last_message_id": "integer",
  "last_message": {
    "id": "integer",
    "app_id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "attachment_count": "integer",
    "attachments": [
      "object"
    ],
    "embed_id": "integer",
    "meeting_id": "integer",
    "option_count": "integer",
    "options": [
      "object"
    ],
    "reactions": [
      "object"
    ],
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "created_by_id": "integer",
    "modified_at": "string",
    "modified_by_id": "integer",
    "is_trashed": "boolean"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}