Chat

Methods, permissions, request fields and response schemas for chat.

Read and search

Retrieve current records, history and status.

List accessible organization conversationsFind conversations available to your organization, with their latest message and unread count.GET/chat/conversations

Token scope chat:readActor permission memberAction type read

Pagination: limit 1–100 (default 30); pass the opaque cursor exactly as returned. Legacy ISO cursors remain accepted.

Query parameters

Field	Type	Description and constraints
`cursor`Optional	string	At least 1 characters · At most 256 characters
`limit`Optional	integer	Minimum 1 · Maximum 100

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{items:[ConversationSummary],hasMore:boolean,cursor:string|null}. Each item has conversationId, conversationType, otherParticipantId/name/avatar, lastMessage and unreadCount.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/chat/conversations?limit=20" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "conversationId": {
                "type": "string",
                "format": "uuid"
              },
              "conversationType": {
                "type": "string",
                "enum": [
                  "booking",
                  "org_internal",
                  "org_support"
                ]
              },
              "otherParticipantId": {
                "type": "string",
                "format": "uuid"
              },
              "otherParticipantName": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "otherParticipantAvatarUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "lastMessage": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "conversationId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "senderId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "senderName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "minLength": 0,
                    "maxLength": 5000
                  },
                  "body": {
                    "type": "string",
                    "minLength": 0,
                    "maxLength": 5000
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "text",
                      "system",
                      "blocked"
                    ]
                  },
                  "metadata": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "additionalProperties": true,
                    "description": "Platform scrape metadata. Keep credentials out of this field."
                  },
                  "deletedAt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "clientRequestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "id",
                  "conversationId",
                  "senderId",
                  "body",
                  "kind",
                  "createdAt"
                ],
                "additionalProperties": true
              },
              "unreadCount": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "messaging": {
                "type": "object",
                "properties": {
                  "canSend": {
                    "type": "boolean"
                  },
                  "restrictions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "party": {
                          "type": "string",
                          "minLength": 0,
                          "maxLength": 5000
                        },
                        "subjectType": {
                          "type": "string",
                          "minLength": 0,
                          "maxLength": 5000
                        },
                        "subjectId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "displayName": {
                          "type": "string",
                          "minLength": 0,
                          "maxLength": 5000
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "banned",
                            "closed"
                          ]
                        },
                        "reason": {
                          "type": "string",
                          "minLength": 0,
                          "maxLength": 5000
                        },
                        "changedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "required": [],
                      "additionalProperties": true
                    }
                  }
                },
                "required": [
                  "canSend",
                  "restrictions"
                ],
                "additionalProperties": true
              }
            },
            "required": [
              "conversationId",
              "conversationType",
              "otherParticipantId",
              "unreadCount"
            ],
            "additionalProperties": true
          }
        },
        "cursor": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 0,
          "maxLength": 256
        },
        "hasMore": {
          "type": "boolean"
        }
      },
      "required": [
        "items",
        "cursor",
        "hasMore"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Read conversation historyRead a conversation page and the current messaging permissions before replying.GET/chat/conversations/:conversationId/messages

Token scope chat:readActor permission memberAction type read

Pagination: Newest first; limit 1–100 (default 20); nextCursor is a message UUID, null means exhausted.

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.

Query parameters

Field	Type	Description and constraints
`cursor`Optional	string · uuid
`limit`Optional	integer	Minimum 1 · Maximum 100

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{messages:[...],nextCursor:string|null,messaging:{...}}. Messages include id, conversationId, senderId, senderName, body, kind, metadata, deletedAt and createdAt.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/chat/conversations/$CONVERSATION_ID/messages?limit=20" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "messages": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "conversationId": {
                "type": "string",
                "format": "uuid"
              },
              "senderId": {
                "type": "string",
                "format": "uuid"
              },
              "senderName": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 0,
                "maxLength": 5000
              },
              "body": {
                "type": "string",
                "minLength": 0,
                "maxLength": 5000
              },
              "kind": {
                "type": "string",
                "enum": [
                  "text",
                  "system",
                  "blocked"
                ]
              },
              "metadata": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": true,
                "description": "Platform scrape metadata. Keep credentials out of this field."
              },
              "deletedAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "clientRequestId": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "id",
              "conversationId",
              "senderId",
              "body",
              "kind",
              "createdAt"
            ],
            "additionalProperties": true
          }
        },
        "nextCursor": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "messaging": {
          "type": "object",
          "properties": {
            "canSend": {
              "type": "boolean"
            },
            "restrictions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "party": {
                    "type": "string",
                    "minLength": 0,
                    "maxLength": 5000
                  },
                  "subjectType": {
                    "type": "string",
                    "minLength": 0,
                    "maxLength": 5000
                  },
                  "subjectId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "displayName": {
                    "type": "string",
                    "minLength": 0,
                    "maxLength": 5000
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "banned",
                      "closed"
                    ]
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 0,
                    "maxLength": 5000
                  },
                  "changedAt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  }
                },
                "required": [],
                "additionalProperties": true
              }
            }
          },
          "required": [
            "canSend",
            "restrictions"
          ],
          "additionalProperties": true
        }
      },
      "required": [
        "messages",
        "nextCursor"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Read total unread countGet the actor's total unread count across accessible conversations.GET/chat/unread-count

Token scope chat:readActor permission memberAction type read

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{count:number} for the actor's accessible conversations.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/chat/unread-count" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "count"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Read profiles shared in the conversationShared profile array. Sensitive credentials and hidden profile-section text are redacted in automation responses by default.GET/chat/conversations/:conversationId/profiles

Token scope chat:readActor permission memberAction type read

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Shared profile array. Sensitive credentials and hidden profile-section text are redacted in automation responses by default.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/chat/conversations/$CONVERSATION_ID/profiles" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "displayName": {
            "type": "string",
            "minLength": 0,
            "maxLength": 5000
          },
          "platform": {
            "type": "string",
            "minLength": 0,
            "maxLength": 5000
          },
          "photoUrl": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 0,
            "maxLength": 5000
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "completed",
              "cancelled"
            ]
          },
          "twoFactorKey": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 0,
            "maxLength": 5000
          }
        },
        "required": [
          "id",
          "displayName",
          "platform",
          "photoUrl",
          "status"
        ],
        "additionalProperties": true
      }
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Read the client conversation recapAuthorized client recap; the existing service role and conversation checks apply.GET/chat/conversations/:conversationId/client-recap

Token scope chat:readActor permission memberAction type read

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Authorized client recap; the existing service role and conversation checks apply.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/chat/conversations/$CONVERSATION_ID/client-recap" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "userId": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 0,
          "maxLength": 5000
        },
        "memberSince": {
          "type": "string",
          "format": "date-time"
        },
        "totalRentals": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "activeRentals": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "totalSpentCents": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "userId",
        "name",
        "memberSince",
        "totalRentals",
        "activeRentals",
        "totalSpentCents"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Read the provider conversation recapOrganization provider recap, rental context and current messaging state.GET/chat/conversations/:conversationId/agent-recap

Token scope chat:readActor permission memberAction type read

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Organization provider recap, rental context and current messaging state.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/chat/conversations/$CONVERSATION_ID/agent-recap" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "userId": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 0,
          "maxLength": 5000
        },
        "memberSince": {
          "type": "string",
          "format": "date-time"
        },
        "accountsOperated": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "rentedNow": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "totalEarnedCents": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "userId",
        "name",
        "memberSince",
        "accountsOperated",
        "rentedNow",
        "totalEarnedCents"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Create and import

Add records, prepare imports or start a new setup.

Find or create a user conversationFind or create a conversation with a client who has a real prior booking.POST/chat/conversations/with-user/:userId

Token scope chat:writeActor permission memberAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`userId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{conversationId:string}; external clients require a real prior booking with this organization. Arbitrary unsolicited DMs and customer impersonation are not allowed.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/chat/conversations/with-user/$USER_ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "conversationId": {
          "type": "string",
          "format": "uuid"
        }
      },
      "required": [
        "conversationId"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Find or create a staff conversationFind or create a staff conversation after organization membership checks.POST/chat/conversations/team/:userId

Token scope chat:writeActor permission memberAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`userId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{conversationId:string}; target must satisfy organization/team membership checks.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/chat/conversations/team/$USER_ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "conversationId": {
          "type": "string",
          "format": "uuid"
        }
      },
      "required": [
        "conversationId"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Update and configure

Change existing records, assignments and configuration.

Reply in an organization conversationReply as the issuing actor in an existing accessible conversation.POST/chat/conversations/:conversationId/messages

Token scope chat:writeActor permission memberAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Before you use it

The actor must be a participant or staff with organization chat access. Empty text is only allowed when attachments are present. Public image URLs must pass the existing upload allowlist; document URLs must come from authenticated attachment upload. Never replay your own bot message webhook as a new client message.

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.

Request body

Field Type Description and constraints

bodyRequired string At least 0 characters · At most 5000 characters

attachmentsOptional

array of object

At least 0 items · At most 10 items

Nested fields

Field	Type	Description and constraints
`url`Required	string	At least 1 characters · At most 2048 characters
`mimeType`Required	string	At least 1 characters · At most 128 characters
`name`Optional	string	At least 0 characters · At most 200 characters
`width`Optional	integer	Minimum 1 · Maximum 16384
`height`Optional	integer	Minimum 1 · Maximum 16384
`size`Optional	integer	Minimum 1 · Maximum 5242880

clientRequestIdOptional string · uuid

Explore this request

Edit example fields and validate the request against its schema.

What you receive

201 {status:'accepted',messageId,message:{id,conversationId,senderId,senderName,body,kind,metadata,createdAt,clientRequestId?}}. Moderation rejection is 422 error.code=CHAT_MESSAGE_BLOCKED and was not delivered. An uncertain commit is 503 error.code=CHAT_DELIVERY_UNCERTAIN: retry with the SAME Idempotency-Key.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/chat/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"body":"Thanks — I’m checking the rental details now."}'

Full JSON request schema

{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "minLength": 0,
      "maxLength": 5000
    },
    "attachments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048
          },
          "mimeType": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 200
          },
          "width": {
            "type": "integer",
            "minimum": 1,
            "maximum": 16384
          },
          "height": {
            "type": "integer",
            "minimum": 1,
            "maximum": 16384
          },
          "size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5242880
          }
        },
        "required": [
          "url",
          "mimeType"
        ],
        "additionalProperties": false
      },
      "maxItems": 10,
      "minItems": 0
    },
    "clientRequestId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false
}

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "accepted"
          ]
        },
        "messageId": {
          "type": "string",
          "format": "uuid"
        },
        "message": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "conversationId": {
              "type": "string",
              "format": "uuid"
            },
            "senderId": {
              "type": "string",
              "format": "uuid"
            },
            "senderName": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 0,
              "maxLength": 5000
            },
            "body": {
              "type": "string",
              "minLength": 0,
              "maxLength": 5000
            },
            "kind": {
              "type": "string",
              "enum": [
                "text",
                "system",
                "blocked"
              ]
            },
            "metadata": {
              "type": [
                "object",
                "null"
              ],
              "additionalProperties": true,
              "description": "Platform scrape metadata. Keep credentials out of this field."
            },
            "deletedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            },
            "clientRequestId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "id",
            "conversationId",
            "senderId",
            "body",
            "kind",
            "createdAt"
          ],
          "additionalProperties": true
        }
      },
      "required": [
        "status",
        "messageId",
        "message"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Find the conversation for a rentalLocate the existing rental conversation without sending a message.POST/chat/conversations/for-booking/:bookingId

Token scope chat:readActor permission memberAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`bookingId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{conversationId:string}; checks access to the existing rental conversation; does not send a message.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/chat/conversations/for-booking/$BOOKING_ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "conversationId": {
          "type": "string",
          "format": "uuid"
        }
      },
      "required": [
        "conversationId"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Lifecycle and actions

Manage transitions, delivery and provider workflows.

Advance the read markerMove the read marker to a message in this conversation and update unread counts.POST/chat/conversations/:conversationId/read

Token scope chat:writeActor permission memberAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.

Request body

Field	Type	Description and constraints
`messageId`Required	string · uuid

Explore this request

Edit example fields and validate the request against its schema.

What you receive

200 {unreadCount,unreadDelta}. The message must belong to this accessible conversation.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/chat/conversations/$CONVERSATION_ID/read" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"messageId":"923ee3b1-2b21-4ce3-8c2c-679e22867541"}'

Full JSON request schema

{
  "type": "object",
  "properties": {
    "messageId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "messageId"
  ],
  "additionalProperties": false
}

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "unreadCount": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "unreadDelta": {
          "type": "integer"
        }
      },
      "required": [
        "unreadCount",
        "unreadDelta"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Hide a conversation for the actor{success:true}; hides locally for this actor without deleting the customer's history.POST/chat/conversations/:conversationId/hide

Token scope chat:writeActor permission memberAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

{success:true}; hides locally for this actor without deleting the customer's history.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/chat/conversations/$CONVERSATION_ID/hide" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        }
      },
      "required": [
        "success"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Remove and disconnect

Remove a record, revoke access or end a connection.

Delete your own messageDelete a message you originally sent in the specified conversation.DELETE/chat/conversations/:conversationId/messages/:messageId

Token scope chat:writeActor permission memberAction type destructive

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.
`messageId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

200 {id,conversationId}. Only the original sender can delete; conversation ID must match.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X DELETE "$BASE/chat/conversations/$CONVERSATION_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "conversationId": {
          "type": "string",
          "format": "uuid"
        }
      },
      "required": [
        "id",
        "conversationId"
      ],
      "additionalProperties": false
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.