Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Communication Conversations API
description: Unified OpenAPI specification for communication domain
version: '3.0'
x-generated:
sourceFiles:
- contact_channels.json
- communication.json
- staff_notification.json
- business_phone_numbers.json
- legacy_v1_communication.json
- activity_message.json
- communication.json
- conversations.json
- notification_template.json
- legacy_v2_communication.json
- messages.json
pathNormalizations:
- file: communication.json
basePath: /business/communication
transformations:
- original: /channels
normalized: /business/communication/channels
basePath: /business/communication
- original: /channels/{uid}
normalized: /business/communication/channels/{uid}
basePath: /business/communication
- original: /messages
normalized: /business/communication/messages
basePath: /business/communication
- original: /messages/{messageUid}
normalized: /business/communication/messages/{messageUid}
basePath: /business/communication
- original: /sessions
normalized: /business/communication/sessions
basePath: /business/communication
- original: /sessions/typing
normalized: /business/communication/sessions/typing
basePath: /business/communication
- original: /sessions/{uid}
normalized: /business/communication/sessions/{uid}
basePath: /business/communication
- file: legacy_v1_communication.json
basePath: /platform/v1
transformations:
- original: /conversations
normalized: /platform/v1/conversations
basePath: /platform/v1
- original: /clients/{client_id}/conversations
normalized: /platform/v1/clients/{client_id}/conversations
basePath: /platform/v1
- original: /messages
normalized: /platform/v1/messages
basePath: /platform/v1
- original: /numbers/dedicated_numbers/assign
normalized: /platform/v1/numbers/dedicated_numbers/assign
basePath: /platform/v1
- original: /numbers/dedicated_numbers/set_two_way_texting_status
normalized: /platform/v1/numbers/dedicated_numbers/set_two_way_texting_status
basePath: /platform/v1
- original: /numbers/twilio
normalized: /platform/v1/numbers/twilio
basePath: /platform/v1
- original: /numbers/twilio/{sub_account_id}
normalized: /platform/v1/numbers/twilio/{sub_account_id}
basePath: /platform/v1
- file: conversations.json
basePath: /v2
transformations:
- original: /conversations/{id}
normalized: /v2/conversations/{id}
basePath: /v2
- file: legacy_v2_communication.json
basePath: /v2
transformations:
- original: /conversations/{conversation_id}/messages
normalized: /v2/conversations/{conversation_id}/messages
basePath: /v2
- file: messages.json
basePath: /business/messaging
transformations:
- original: /v1/channels
normalized: /business/messaging/v1/channels
basePath: /business/messaging
- original: /v1/channels/typing
normalized: /business/messaging/v1/channels/typing
basePath: /business/messaging
pathConflicts: []
componentConflicts:
- type: schema
name: ErrorResponse
resolution: Renamed to ErrorResponse_communication
files:
- merged
- communication.json
- type: schema
name: ErrorResponse
resolution: Renamed to ErrorResponse_staff_notification
files:
- merged
- staff_notification.json
- type: schema
name: Response
resolution: Renamed to Response_business_phone_numbers
files:
- merged
- business_phone_numbers.json
- type: schema
name: ErrorResponse
resolution: Renamed to ErrorResponse_business_phone_numbers
files:
- merged
- business_phone_numbers.json
- type: schema
name: ErrorResponse
resolution: Renamed to ErrorResponse_activity_message
files:
- merged
- activity_message.json
- type: schema
name: Response
resolution: Renamed to Response_communication
files:
- merged
- communication.json
- type: schema
name: ErrorResponse
resolution: Renamed to ErrorResponse_conversations
files:
- merged
- conversations.json
totalPaths: 36
totalComponents: 50
servers:
- url: https://api.vcita.biz
description: Unified API Gateway server
tags:
- name: Conversations
paths:
/platform/v1/clients/{client_id}/conversations:
get:
description: '## Overview
Gets a list of conversations for a client.
## Authentication
**Available for Staff, App, and Directory Tokens.**'
parameters:
- description: Client UID
in: path
name: client_id
required: true
schema:
type: string
- description: 'Page number (default: 1)'
in: query
name: page
required: false
schema:
type: integer
- description: 'Results per page (default: 25, max: 50)'
in: query
name: per_page
required: false
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
example:
data:
conversations:
- business_id: 2f27ca024eb96133
business_unread: false
client_id: od0tuoli2prraw3y
client_unread: false
created_at: '2025-08-05T06:56:33.583Z'
deep_link: /app/conversations/uuk21b7xv53er6zq
id: uuk21b7xv53er6zq
last_business_action: ''
last_client_action: null
staff_id: 6ad7601fd821c8d2
title: null
updated_at: '2025-08-05T06:56:33.583Z'
status: OK
summary: Get Conversations For A Client
tags:
- Conversations
x-amazon-apigateway-auth:
type: NONE
x-amazon-apigateway-integration:
httpMethod: GET
responses:
default:
statusCode: '200'
type: http_proxy
uri: https:///platform/v1/clients/{client_id}/conversations
x-auth-type: Application & Application User
security:
- Bearer: []
operationId: getPlatformV1ClientsByClientIdConversations
x-operation-id-source: derived
/platform/v1/conversations:
get:
description: '## Overview
Gets a list of conversations.
Available for **Staff and Directory tokens**. Directory tokens require the `X-On-Behalf-Of` header with the target business UID.'
parameters:
- description: 'Page number of results. Default: 1'
in: query
name: page
required: false
schema:
type: integer
- description: 'How many items to return per page. Default: 25. Max: 100'
in: query
name: per_page
required: false
schema:
type: integer
- description: Business UID to act on behalf of. Required for Directory tokens.
in: header
name: X-On-Behalf-Of
required: false
schema:
type: string
- description: Filter conversations by folder. Only honored for staff (user) tokens; admin/app/directory tokens silently ignore this parameter. Unknown values silently fall through to unfiltered results. (e.g., "inbox", "follow_up", "sent", "archived", "attention", "trash", "all")
in: query
name: folder
required: false
schema:
type: string
enum:
- inbox
- follow_up
- sent
- archived
- attention
- trash
- all
responses:
'200':
description: Success
content:
application/json:
example:
data:
conversations:
- business_id: 2f27ca024eb96133
business_unread: false
client_id: od0tuoli2prraw3y
client_unread: false
created_at: '2025-08-05T06:56:33.583Z'
deep_link: /app/conversations/uuk21b7xv53er6zq
id: uuk21b7xv53er6zq
last_business_action: ''
last_client_action: null
staff_id: 6ad7601fd821c8d2
title: null
updated_at: '2025-08-05T06:56:33.583Z'
- business_id: 2f27ca024eb96133
business_unread: false
client_id: dn7ucrylnqxrb52l
client_unread: false
created_at: '2025-08-05T06:56:34.629Z'
deep_link: /app/conversations/lzth35ivm33uo073
id: lzth35ivm33uo073
last_business_action: ''
last_client_action: null
staff_id: 6ad7601fd821c8d2
title: null
updated_at: '2025-08-05T06:56:34.629Z'
status: OK
summary: Get Conversations
tags:
- Conversations
x-amazon-apigateway-auth:
type: NONE
x-amazon-apigateway-integration:
httpMethod: GET
responses:
default:
statusCode: '200'
type: http_proxy
uri: https:///platform/v1/conversations
x-auth-type: Application & Application User
security:
- Bearer: []
operationId: getPlatformV1Conversations
x-operation-id-source: derived
/v2/conversations/{id}:
put:
summary: Update a conversation (archive, spam, business_unread, follow-up, soft delete)
description: '## Overview
Updates a single conversation. This endpoint is used for several distinct operations against the same conversation resource:
- Archive / unarchive
- Mark as spam / not spam
- Mark as read / unread for the business side (`business_unread`)
- Soft delete (`deleted`)
- **Create, update, complete, or remove a follow-up reminder for the requesting staff member**
All fields are optional in the request body — send only the fields you want to change. Only fields that are present in the request body are evaluated.
Available for **Staff tokens**.
## Follow-up flow
Follow-ups in vcita are scoped to a single staff member on a single conversation, and are stored on the underlying `Collaborator` record (per staff/conversation), not on the conversation itself. Sending follow-up fields on this endpoint always operates on the follow-up record of the **staff identified by the bearer token**.
The endpoint branches based on the combination of `follow_up` and `archived` in the request body:
| Sent fields | Behavior |
|---|---|
| `follow_up: true`, no `archived` (or `archived: false`) | **Create or update** a follow-up for the requesting staff. Creates a Collaborator if one does not already exist. Sets `follow_up=true`, `follow_up_message`, and optionally `follow_up_date`. If the conversation was archived, it is automatically unarchived. If a `follow_up_message` is provided without a `follow_up_date`, an internal text message is added to the conversation. |
| `follow_up: true`, `archived: true` | **Remove** the follow-up (used to dismiss/snooze). If `complete_follow_up: true` is also sent, the follow-up is marked as completed. |
| `follow_up: false` | **Remove** the follow-up. If `complete_follow_up: true` is also sent, the follow-up is marked as completed. |
Note: The follow-up branch only fires when the request body actually contains a `follow_up` key, and the add/remove logic only fires when the new `follow_up` value differs from the current one (with the exception of the `follow_up: true, archived: true` case, which always removes).
## Permitted update fields
Fields outside of the follow-up flow are permitted via `Conversation::READ_WRITE_PARAMS`: `archived`, `business_unread`, `spam`, `deleted`, `campaign`, `source_type`, `mobile`. The follow-up fields (`follow_up`, `follow_up_date`, `follow_up_message`, `complete_follow_up`) are read separately from the request body and are not part of the permitted attributes list.'
tags:
- Conversations
parameters:
- name: id
in: path
required: true
description: Unique identifier (uid) of the conversation to update (e.g., "89m2pnabgozdvd9f"). If the uid points to a conversation that has been merged into another, the request is automatically routed to the merged target conversation.
schema:
type: string
- name: full_client
in: query
required: false
description: When set to a truthy value, the response client object is rendered in its full representation (instead of the default summary), and the conversation is rendered in its deep representation (adds source/source_data/source_type/sourceable fields and sets `depth` to "deep").
schema:
type: boolean
responses:
'200':
description: Conversation updated successfully. Returns the updated conversation as decorated by ConversationDecorator. Note that `follow_up_date` and `follow_up_message` on the response reflect the values sent in the request (they are exposed on the conversation via accessors but persisted on the per-staff Collaborator record).
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
example:
uid: 89m2pnabgozdvd9f
title: Jane Smith
follow_up: true
follow_up_date: '2026-05-06T10:31:21Z'
follow_up_message: just a test
follow_up_text: Reminder set for tomorrow at 1:31 PM
business_unread: false
spam: false
archived: false
sent: true
received: true
deleted: false
matter_searchable: true
last_user_action_at: '2026-05-05T10:30:00Z'
last_user_action_at_h: Today, 10:30 AM
last_client_action_at: '2026-05-04T16:12:00Z'
last_client_action_at_h: Yesterday, 4:12 PM
last_message:
title: 'Re: Initial consultation'
text: Sounds good, see you then.
message_of: client
extra_data: {}
depth: shallow
message_count: 7
client:
uid: 0c4ac9717ab26f56
first_name: Jane
last_name: Smith
email: jane@example.com
staff:
uid: 5ya4gbwm2c3qoic8
display_name: Ram Almog
has_matter: false
matter: null
'401':
description: Unauthorized. The bearer token is missing, invalid, expired, or not a staff token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- code: unauthorized
message: 401 Unauthorized
'403':
description: Forbidden. The authenticated staff is not allowed to update this conversation (Pundit policy denied access).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- code: forbidden
message: You are not authorized to perform this action.
'404':
description: Not Found. No conversation with the given uid exists, or the conversation belongs to a different business than the one resolved from the bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- code: invalid
field: id
message: Invalid conversation_uid
'422':
description: Unprocessable Entity. The follow-up validation failed. The most common cause is `follow_up_date` being in the past; the staff resolved from the bearer token could not be found is also possible.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- field: follow_up_date
code: invalid
message: Time has already passed.
x-auth-type: Application User
requestBody:
content:
application/json:
schema:
type: object
description: Partial update payload. All fields are optional; send only the fields you want to change.
properties:
follow_up:
type: boolean
description: 'Whether a follow-up should be active on this conversation for the requesting staff. Setting this field is what triggers the follow-up branch. Set to `true` to create/update a follow-up, or `false` to remove it. When combined with `archived: true`, `follow_up: true` removes the follow-up (used to dismiss it from the inbox).'
follow_up_date:
type: string
description: When the follow-up reminder should fire. Accepts any string parseable by Ruby's Time parser, including the JavaScript-style format the UI sends (e.g., "Wed May 06 2026 13:31:21 GMT+0300 (Israel Daylight Time)") and ISO 8601 (e.g., "2026-05-06T10:31:21Z"). Must be in the future. Only consumed when creating/updating a follow-up.
follow_up_message:
type: string
description: Free-text note attached to the follow-up (e.g., "just a test", "call back about pricing"). Defaults to an empty string. When a non-empty `follow_up_message` is sent without a `follow_up_date`, an internal text message is automatically added to the conversation as a record of the follow-up note.
complete_follow_up:
type: boolean
default: false
description: 'Only meaningful when removing a follow-up (i.e., `follow_up: false`, or `follow_up: true` with `archived: true`). When `true`, the follow-up is marked as completed rather than simply dismissed.'
archived:
type: boolean
description: 'Archive (`true`) or unarchive (`false`) the conversation. When sent together with `follow_up: true`, it instead removes the follow-up (see the follow-up branching table above).'
business_unread:
type: boolean
description: Mark the conversation as unread (`true`) or read (`false`) for the business side. When this field is present, the read state is propagated to the relevant staff collaboration record.
spam:
type: boolean
description: Mark the conversation as spam (`true`) or not spam (`false`). When set, the spam state is also applied to the associated client.
deleted:
type: boolean
description: Soft-delete (`true`) the conversation (sets `deleted_at` to the current time). Hard deletion is performed via the DELETE endpoint, not via this field.
campaign:
type: string
description: Free-form campaign tag stored on the conversation.
source_type:
type: string
description: Source classifier of the conversation (e.g., "contact_form", "profile_page", "email_campaign").
mobile:
type: boolean
description: Internal flag indicating whether the conversation originated from a mobile device.
example:
follow_up: true
follow_up_date: Wed May 06 2026 13:31:21 GMT+0300 (Israel Daylight Time)
follow_up_message: just a test
security:
- Conversations: []
operationId: putV2ConversationsById
x-operation-id-source: derived
components:
schemas:
ConversationStaff:
type: object
description: Lightweight staff reference embedded in a conversation.
properties:
uid:
type: string
description: Unique identifier of the staff member that owns the conversation (e.g., "5ya4gbwm2c3qoic8").
display_name:
type: string
description: Display name of the staff member (e.g., "Jane Doe").
Conversation:
type: object
description: Represents a conversation (engagement) between a business and a client. Returned by the conversation endpoints via ConversationDecorator.
properties:
uid:
type: string
description: Unique identifier of the conversation (e.g., "89m2pnabgozdvd9f").
title:
type: string
description: Title of the conversation. May be redacted to a placeholder when the requesting staff does not have view permission on the client.
follow_up:
type: boolean
description: Whether a follow-up is currently set on this conversation for the requesting staff. The follow-up is stored per staff on the underlying Collaborator record.
follow_up_date:
type: string
format: date-time
description: When the follow-up reminder is scheduled. Null when no scheduled date was set or when no follow-up is active.
follow_up_message:
type: string
description: Free-text note attached to the follow-up (e.g., "call back about pricing").
follow_up_text:
type: string
description: Pre-formatted, localized human-readable string describing the follow-up state (e.g., "Reminder set for tomorrow at 1:31 PM"). Empty string when no follow-up is active.
business_unread:
type: boolean
description: True when the conversation is marked as unread for the business side.
spam:
type: boolean
description: Whether the conversation is marked as spam.
archived:
type: boolean
description: Whether the conversation is archived.
sent:
type: boolean
description: True if the conversation contains at least one outgoing message sent by the business.
received:
type: boolean
description: True if the conversation contains at least one incoming message from the client.
deleted:
type: boolean
description: True when the conversation has been soft-deleted (i.e., deleted_at is not null).
matter_searchable:
type: boolean
description: Internal flag controlling whether the conversation participates in matter-based search.
last_user_action_at:
type: string
format: date-time
description: Timestamp of the most recent action performed by the business side on this conversation.
last_user_action_at_h:
type: string
description: Human-friendly representation of last_user_action_at (e.g., "Today, 10:30 AM" or a date string).
last_client_action_at:
type: string
format: date-time
description: Timestamp of the most recent action performed by the client on this conversation.
last_client_action_at_h:
type: string
description: Human-friendly representation of last_client_action_at.
last_message:
$ref: '#/components/schemas/ConversationLastMessage'
depth:
type: string
enum:
- shallow
- deep
description: Indicates how much detail is included in the response. "deep" is returned when the request asks for the full representation (e.g., "full_client=true").
message_count:
type: integer
description: Total number of messages associated with this conversation.
client:
type: object
description: 'Summary representation of the client participating in the conversation. Includes uid, display name, contact info, and other summary fields produced by ClientDecorator (version: :summary).'
staff:
$ref: '#/components/schemas/ConversationStaff'
has_matter:
type: boolean
description: True when a matter is associated with this conversation.
matter:
type: object
description: Slim representation of the associated matter, when has_matter is true.
require_attention:
type: boolean
description: Only present in the deep representation. True when the conversation is unread for the business or has meetings in business-pending states.
source:
type: string
description: Only present in the deep representation. Original source of the conversation (e.g., URL of the page from which it was created).
source_data:
type: object
description: Only present in the deep representation. Decorated source metadata.
source_type:
type: string
description: Only present in the deep representation. Normalized source type (e.g., "profile_page", "email_campaign", "contact_form").
source_type_h:
type: string
description: Only present in the deep representation. Human-readable, localized source type label.
sourceable_type:
type: string
description: Only present in the deep representation. Class name of the polymorphic source object (when applicable).
sourceable_id:
type: string
description: Only present in the deep representation. UID of the polymorphic source object (when applicable).
ConversationLastMessage:
type: object
description: Compact representation of the most recent message in the conversation. May be null when the conversation has no messages, or when the requesting staff has no collaboration on the conversation and the last message is restricted.
properties:
title:
type: string
description: Title of the last message (subject line, meeting title, invoice header, etc.).
text:
type: string
description: Decorated text of the last message.
message_of:
type: string
description: Identifies who the message is from in the API context (e.g., "client", "staff", "system").
extra_data:
type: object
description: Additional message metadata. Shape depends on message type. For voice calls includes "call_status" and "recording_duration".
ErrorResponse:
type: object
properties:
success:
type: boolean
errors:
type: array
items:
type: object
properties:
field:
type: string
description: The field that caused the error (for validation errors)
code:
type: string
message:
type: string
required:
- code
- message
required:
- success
- errors
example:
success: false
errors:
- field: contact_uid
code: invalid
message: contact_uid is required.
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Provide a valid bearer token in the Authorization header. Example: ''Authorization: Bearer {app_token}'''
Conversations:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Provide a valid staff bearer token in the Authorization header. Example: ''Authorization: Bearer {staff_token}''.'
x-provenance:
method: searched
source: https://developers.intandem.tech:443/reference
harvested: '2026-11-15'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://developers.intandem.tech/reference/availablephonenumberscontroller_findall.md
- https://developers.intandem.tech/reference/businessphonenumberscontroller_create.md
- https://developers.intandem.tech/reference/businessphonenumberscontroller_findall.md
- https://developers.intandem.tech/reference/businessphonenumberscontroller_findone.md
- https://developers.intandem.tech/reference/businessphonenumberscontroller_update.md
- https://developers.intandem.tech/reference/channelscontroller_create.md
- https://developers.intandem.tech/reference/channelscontroller_deletechannel.md
- https://developers.intandem.tech/reference/channelscontroller_updatechannel.md
- https://developers.intandem.tech/reference/contactchannelscontroller_index.md
- https://developers.intandem.tech/reference/delete_platform-v1-numbers-twilio-sub-account-id.md
- https://developers.intandem.tech/reference/delete_v3-communication-notification-templates-uid.md
- https://developers.intandem.tech/reference/get_platform-v1-clients-client-id-conversations-1.md
- https://developers.intandem.tech/reference/get_platform-v1-conversations.md
- https://developers.intandem.tech/reference/get_v2-conversations-conversation-id-messages.md
- https://developers.intandem.tech/reference/get_v3-communication-notification-templates-uid.md
- https://developers.intandem.tech/reference/get_v3-communication-notification-templates.md
- https://developers.intandem.tech/reference/get_v3-communication-staff-notifications-uid.md
- https://developers.intandem.tech/reference/getstaffnotificationstats.md
- https://developers.intandem.tech/reference/listactivitymessages.md
- https://developers.intandem.tech/reference/liststaffnotifications.md
- https://developers.intandem.tech/reference/messagescontroller_createmessage.md
- https://developers.intandem.tech/reference/messagescontroller_updatestatus.md
- https://developers.intandem.tech/reference/post_business-messaging-v1-channels-typing.md
- https://developers.intandem.tech/reference/post_business-messaging-v1-channels.md
- https://developers.intandem.tech/reference/post_platform-v1-messages.md
- https://developers.intandem.tech/reference/post_platform-v1-numbers-dedicated-numbers-assign.md
- https://developers.intandem.tech/reference/post_platform-v1-numbers-twilio.md
- https://developers.intandem.tech/reference/post_v3-communication-notification-templates.md
- https://developers.intandem.tech/reference/post_v3-communication-staff-notifications.md
- https://developers.intandem.tech/reference/put_platform-v1-numbers-dedicated-numbers-set-two-way-texting-status.md
- https://developers.intandem.tech/reference/put_v2-conversations-id.md
- https://developers.intandem.tech/reference/put_v3-communication-notification-templates-uid.md
- https://developers.intandem.tech/reference/quotascontroller_getquota.md
- https://developers.intandem.tech/reference/recordingscontroller_deletevoicecallrecording.md
- https://developers.intandem.tech/reference/recordingscontroller_updatevoicecallrecording.md
- https://developers.intandem.tech/reference/reportscontroller_getvoicecallstats.md
- https://developers.intandem.tech/reference/sendactivitymessage.md
- https://developers.intandem.tech/reference/sessionscontroller_createsession.md
- https://developers.intandem.tech/reference/sessionscontroller_getsession.md
- https://developers.intandem.tech/reference/sessionscontroller_logicdelete.md
- https://developers.intandem.tech/reference/sessionscontroller_updatestatus.md
- https://developers.intandem.tech/reference/sessionstypingcontroller_typingstatus.md
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://artifacts.apis.io/vcita/openapi/vcita-conversations-api-openapi.yml