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 {WEAVY-URL}/api/conversations
-H "Authorization: Bearer {ACCESS-TOKEN}"
--json "{ 'members': [ 'bugs-bunny' ] }"

curl {WEAVY-URL}/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",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "last_message": {
    "id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "is_starred": "boolean",
    "is_subscribed": "boolean",
    "is_trashed": "boolean",
    "created_at": "string",
    "updated_at": "string"
  },
  "is_pinned": "boolean",
  "is_trashed": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_unread": "boolean",
  "permissions": [
    "string"
  ]
}

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 {WEAVY-URL}/api/conversations/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
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",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "last_message": {
    "id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "is_starred": "boolean",
    "is_subscribed": "boolean",
    "is_trashed": "boolean",
    "created_at": "string",
    "updated_at": "string"
  },
  "is_pinned": "boolean",
  "is_trashed": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_unread": "boolean",
  "permissions": [
    "string"
  ]
}

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. "id" or "id+desc"

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

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

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 {WEAVY-URL}/api/conversations?take=25
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK
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",
      "updated_at": "string",
      "is_pinned": "boolean",
      "is_trashed": "boolean",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "is_unread": "boolean",
      "permissions": [
        "string"
      ]
    }
  ],
  "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 {WEAVY-URL}/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 {WEAVY-URL}/api/conversations/badge
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 OK

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 {WEAVY-URL}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Mark as unread

Mark a conversation as unread for the authenticated user, 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 {WEAVY-URL}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Pin conversation

Pin a conversation for the authenticated user.

PUT /api/conversations/{id}/pin

Path parameters

id integer required: Conversation (app) id.

Example request

curl -X PUT {WEAVY-URL}/api/conversations/1/pin
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Unpin conversation

Unpin a conversation for the authenticated user.

DELETE /api/conversations/{id}/pin

Path parameters

id integer required: Conversation (app) id.

Example request

curl -X DELETE {WEAVY-URL}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

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 {WEAVY-URL}/api/conversations/1/delivered
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Conversations

Create conversation

Body parameters

Example request

Response codes

Response schema

Get conversation

Path parameters

Query parameters

Example request

Response codes

Response schema

List conversations

Query parameters

Example request

Response codes

Response schema

Indicate typing

Path parameters

Example request

Response codes

Count unread conversations

Example request

Response codes

Response schema

Mark as read

Path parameters

Query parameters

Example request

Response codes

Mark as unread

Path parameters

Example request

Response codes

Pin conversation

Path parameters

Example request

Response codes

Unpin conversation

Path parameters

Example request

Response codes

Set as delivered

Path parameters

Example request

Response codes

Support