Conversations

The Conversations API has methods for creating, and managing conversations (chat apps).

Create chat

Creates a non-contextual chat app (private chat or chat room).

If name is omitted and only one member is specified, a private chat is created. If there is already a chat between the creator and specified member, that instance is returned instead of creating a new chat.

If name is specified, or member count is more than one, a chat room is created (when name is omitted, the name of the chat will be the participant(s) names).

POST /api/conversations
Body parameters
name string

Name of room to create, or null to auto-generate a name based on room members.

members array of integers required

The members of the conversation.

Response codes

201 Created

{
  "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",
  "last_message_id": "integer",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

400 Bad Request

Code sample
curl https://{WEAVY-SERVER}/api/conversations
-H "Authorization: Bearer {ACCESS-TOKEN}"
--json "{ 'members': [ 4 ] }"

curl https://{WEAVY-SERVER}/api/conversations
-H "Authorization: Bearer {ACCESS-TOKEN}"
--json "{ 'name': 'My chat room', 'members': [1, 4, 14] }"

List conversations

List all chat apps where the authenticated user is member.

GET /api/conversations
Query parameters
unread boolean

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

contextual boolean

true to lists contextual apps, false to list non-contextual apps; when not specified both types are listed.

type string

Guid of app type to list.

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 0 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 boolean

false to skip counting the total number of matching items; default is true.

count_only boolean

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

Response codes

200 Success

{
  "data": [
    "object"
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}
Code sample
curl https://{WEAVY-SERVER}/api/conversations?top=20
-H "Authorization: Bearer {ACCESS-TOKEN}"

Get conversation

Get conversation (chat app).

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

App id of the chat to return.

Query parameters
trashed boolean

true to return conversation even if trashed, otherwise false.

Response codes

200 Success

{
  "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",
  "last_message_id": "integer",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}
Code sample
curl https://{WEAVY-SERVER}/api/conversations/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Count unread conversations

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

GET /api/conversations/badge
Response codes

200 Success

{
  "private": "integer",
  "rooms": "integer",
  "chat": "integer"
}
Code sample
curl https://{WEAVY-SERVER}/api/conversations/badge
-H "Authorization: Bearer {ACCESS-TOKEN}"

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.

Response codes

200 Success

{
  "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",
  "last_message_id": "integer",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

404 Not Found

Code sample
curl -X PUT https://{WEAVY_SERVER}/api/conversations/1/delivered
-H "Authorization: Bearer {ACCESS-TOKEN}"

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.

Response codes

200 Success

{
  "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",
  "last_message_id": "integer",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

404 Not Found

Code sample
curl -X PUT https://{WEAVY_SERVER}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"

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.

Response codes

200 Success

{
  "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",
  "last_message_id": "integer",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

404 Not Found

Code sample
curl -X DELETE https://{WEAVY_SERVER}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"

Pin conversation

Pin a conversation.

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

Conversation (app) id.

Response codes

200 Success

{
  "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",
  "last_message_id": "integer",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

404 Not Found

Code sample
curl -X PUT https://{WEAVY_SERVER}/api/conversations/1/pin
-H "Authorization: Bearer {ACCESS-TOKEN}"

Unpin conversation

Unpin a conversation.

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

Conversation (app) id.

Response codes

200 Success

{
  "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",
  "last_message_id": "integer",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_pinned": "boolean",
  "is_unread": "boolean"
}

404 Not Found

Code sample
curl -X DELETE https://{WEAVY_SERVER}/api/conversations/1/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"
Weavy Docs