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

Ask AI
Support

To access live chat with our developer success team you need a Weavy account.

Sign in or create a Weavy account