> ## Documentation Index > Fetch the complete documentation index at: https://docs.zivio.com/llms.txt > Use this file to discover all available pages before exploring further. # Message a supplier about a project (start or continue their thread) > Sends a message to the named supplier on their project thread, mirroring the web UI's messaging: it starts the conversation if none exists or appends to the existing one — the same call either way, so retries cannot duplicate threads. Recipients (all the supplier's users plus the project's messaging members) are notified by email automatically. The supplier must already be engaged on the project (invited, matched, or bidding) — invite first via POST /projects/{id}/invitations otherwise. ## OpenAPI ````yaml /api-reference/v4/openapi.json post /projects/{id}/conversations openapi: 3.1.0 info: title: API V4 version: '4' description: >- OAuth 2.0 secured API. Obtain an access token using client credentials to access protected endpoints. The regional endpoints listed below serve every Zivio organisation, so each request — including the token request — must carry a `zivio-tenant-id` header identifying yours. Requests without it are rejected with a 404 before any token is checked. contact: name: API Support email: support@zivio.com servers: - url: https://api.zivio.net/api/v4 description: Global API Router - url: https://api.eu.zivio.net/api/v4 description: EU Data Region - url: https://api.uk.zivio.net/api/v4 description: UK Data Region - url: https://api.us.zivio.net/api/v4 description: US Data Region security: - oauth2: [] tenantId: [] paths: /projects/{id}/conversations: post: tags: - Projects summary: Message a supplier about a project (start or continue their thread) description: >- Sends a message to the named supplier on their project thread, mirroring the web UI's messaging: it starts the conversation if none exists or appends to the existing one — the same call either way, so retries cannot duplicate threads. Recipients (all the supplier's users plus the project's messaging members) are notified by email automatically. The supplier must already be engaged on the project (invited, matched, or bidding) — invite first via POST /projects/{id}/invitations otherwise. operationId: postProjectsByIdConversations parameters: - name: id in: path required: true schema: type: integer description: Project ID example: 123 requestBody: required: true content: application/json: schema: type: object properties: supplier_id: type: integer description: The supplier to message; must be engaged on the project. example: 45 body: type: string description: The message text. example: >- Could you confirm who will lead accessibility testing? Please respond by Friday. required: - supplier_id - body responses: '201': description: The message sent, with its conversation content: application/json: schema: type: object example: project_id: 123 conversation: conversation_id: 31 subject: 'Re: Website Redesign (Acme Consulting)' kind: proposal supplier: id: 45 name: Acme Consulting message: message_id: 87 sender: id: 1 name: Jane Smith side: client body: Could you confirm who will lead accessibility testing? sent_at: '2026-07-01T12:00:00Z' attachments: [] '401': description: >- Unauthorized - the access token is missing, expired, revoked or malformed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_token error_description: >- The access token provided is expired, revoked, malformed, or invalid for other reasons '403': description: Forbidden - insufficient scope content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient_scope error_description: >- The request requires higher privileges than provided by the access token required_scope: project_conversations:write provided_scopes: - welcome:read '422': description: >- Missing body or supplier_id, or the supplier has no engagement on the project content: application/json: schema: type: object example: error: supplier_not_engaged message: >- Supplier 45 has no engagement on project 123 - invite them first (POST /projects/{id}/invitations) security: - oauth2: - project_conversations:write tenantId: [] components: schemas: Error: type: object description: Error envelope returned by every non-2xx V4 response properties: error: type: string example: insufficient_scope error_description: type: string message: type: string details: type: object additionalProperties: true required_scope: type: string example: projects:read provided_scopes: type: array items: type: string securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client credentials. The access token from POST /oauth/token is sent as a bearer token. Request only the scopes you need. flows: clientCredentials: tokenUrl: https://api.zivio.net/api/v4/oauth/token scopes: bank_accounts:read: Read bank account details on suppliers and the org. catalogs:read: Read catalog items. cost_centers:read: Read cost center records. eoi_responses:read: Read responses to expressions of interest. eois:read: Read expressions of interest. offers:read: Read offers for projects. org_units:read: Read your organization unit hierarchy. org_users:read: Read members of your organization. resources:read: Read resource (worker) records. sales_invoices:read: Read invoices issued to clients. sales_milestones:read: Read milestones on sales engagements. skill_categories:read: Read the skill category taxonomy. skill_taxonomies:read: Read skill taxonomy structure. skills:read: Read individual skills. supplier_documents:read: Read documents uploaded by suppliers. supplier_lists:read: Read curated lists of suppliers. supplier_users:read: Read users belonging to supplier organizations. tax_types:read: Read configured tax types. users:read: Read user profiles. variation_orders:read: Read variation orders on projects. welcome:read: 'Required: confirms your identity to the application.' bid_evaluations:read: >- Read evaluation scorecards for bids, including criterion scores and quality, cost and total scores. bid_evaluations:write: >- Score bids against a project's quality criteria and override calculated cost scores. bids:read: Read bids submitted on projects. bids:write: >- Shortlist, select, eliminate and reinstate bids submitted on projects. invoices:read: Read invoices on projects. invoices:write: Create and update invoices. notes:read: Read notes on projects and EOIs. notes:write: Create and update notes on projects and EOIs. project_approvals:read: Read project approval workflows. project_approvals:write: Create and update project approval workflows. project_conversations:read: Read messages exchanged with suppliers on a project. project_conversations:write: Send messages to suppliers on a project. project_invitations:read: Read supplier invitations on projects. project_invitations:write: Invite suppliers to bid on projects. project_questions:read: Read supplier clarification questions on projects. project_questions:write: Answer and approve supplier clarification questions. projects:read: Read projects. projects:write: Create and update projects. milestones:read: Read milestones on projects. milestones:write: Create and update milestones. orgs:read: Read organization records. orgs:write: Create and update organization records. purchase_orders:read: Read purchase orders. purchase_orders:write: Create and update purchase orders. reviews:read: Read reviews left on suppliers. reviews:write: Create and update reviews. suppliers:read: Read supplier profiles. suppliers:write: Create and update supplier profiles. raw_scorecard_entries:write: Create and update raw scorecard entries. raw_scorecard_entries:read: Read raw scorecard entries. tasks:read: >- Read the acting user's task queue, including outstanding approvals and items to review. tasks:write: Complete and dismiss tasks in the acting user's task queue. act_as_user: >- Make requests as another user within the token holder's delegation boundary. tenantId: type: apiKey name: zivio-tenant-id in: header description: >- Your Zivio organisation identifier. The regional API endpoints serve every Zivio organisation, so each request must identify yours. ````