1. Reference
  2. Web API
  3. Conversations

Conversations

The Conversations API has methods for creating, and managing conversations.

Create chat

Create a chat room or private chat. If member count is more than one, a chat room is created. If 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",
  "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",
  "member_count": "integer",
  "members": [
    "object"
  ],
  "user_id": "integer",
  "last_message_id": "integer",
  "is_pinned": "boolean",
  "is_unread": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

400 Bad Request

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

List conversations

List the conversations for the authenticated user.

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 a conversation.

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

Conversation (app) id.

Query parameters
trashed boolean

true to return conversation even if trashed, otherwise false.

Response codes

200 Success

{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "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",
  "member_count": "integer",
  "members": [
    "object"
  ],
  "user_id": "integer",
  "last_message_id": "integer",
  "is_pinned": "boolean",
  "is_unread": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "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}"

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

Id of last read message.

Response codes

200 Success

{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "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",
  "member_count": "integer",
  "members": [
    "object"
  ],
  "user_id": "integer",
  "last_message_id": "integer",
  "is_pinned": "boolean",
  "is_unread": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

404 Not Found

Code sample
$ curl -X PUT {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",
  "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",
  "member_count": "integer",
  "members": [
    "object"
  ],
  "user_id": "integer",
  "last_message_id": "integer",
  "is_pinned": "boolean",
  "is_unread": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

404 Not Found

Code sample
$ curl -X DELETE {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",
  "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",
  "member_count": "integer",
  "members": [
    "object"
  ],
  "user_id": "integer",
  "last_message_id": "integer",
  "is_pinned": "boolean",
  "is_unread": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

404 Not Found

Code sample
$ curl -X PUT {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",
  "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",
  "member_count": "integer",
  "members": [
    "object"
  ],
  "user_id": "integer",
  "last_message_id": "integer",
  "is_pinned": "boolean",
  "is_unread": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

404 Not Found

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