> ## Documentation Index > Fetch the complete documentation index at: https://docs.parley.so/llms.txt > Use this file to discover all available pages before exploring further. # Send a message > Send a message to a session. An idle assistant starts on it right away; a working one reads it at its next step, so you can steer it mid-task. Returns the session as soon as the message is queued, with status working; get the session until its status is idle, then read the reply with GET /sessions/{id}/messages. Sessions started in Word or Outlook can only be continued there. Returns 409 SESSION_BUSY while the session is being summarized or changed, and 429 USAGE_LIMIT_REACHED when the organization has used its Parley AI allowance for the billing period. ## OpenAPI ````yaml https://api.parley.so/openapi.json post /sessions/{id}/messages openapi: 3.1.1 info: title: Parley API version: 1.0.0 description: >- Manage Parley's projects (matters or cases), accounts (client organizations), contacts (people), tasks, custom fields, notes, files, activity, automations, and skills. Records refer to each other as { type, id, name } references; writes take IDs. Errors are { error: { code, message, details } }, where code names what went wrong and each operation lists the codes it can return. In a query string, write a timestamp's offset as Z or %2B, because a raw + arrives as a space. The MCP server at /mcp offers the same data as a smaller set of tools. servers: - url: https://api.parley.so/v1 security: - bearerAuth: [] tags: - name: Projects description: >- A project is a matter or case: it groups the files, notes, activity, and tasks for one engagement, and links to the accounts and contacts it involves. - name: Accounts description: >- An account is a client organization. Contacts belong to it, and projects link to it. - name: Contacts description: >- A contact is a person, optionally belonging to one account and linked to projects. - name: Tasks description: >- A task is a to-do with a status, assignee, and due date, optionally about one project, account, or contact. - name: Fields description: >- Custom fields defined for projects, accounts, contacts, or tasks. Records carry their values in fields, keyed by field name. - name: Notes description: >- Markdown notes on a project, account, or contact. Updates take the version you last read, so concurrent edits fail with 409 VERSION_CONFLICT instead of overwriting. - name: Files description: >- Files and folders of a project, account, contact, or intake, or the organization's Library. Add a file by creating an upload, PUTting its bytes, and adding the upload to a location. - name: Activity description: >- What happened across the organization or on one record: changes, links, notes, files, USCIS case updates, and synced emails and meetings. Each item's kind says which details it carries. - name: Sessions description: >- Conversations with Parley's assistant, from the web app, Word, Outlook, automation runs, and the API. Start one with a message, follow up or steer it while it works, and read its replies. - name: Automations description: >- Instructions Parley's assistant carries out on a schedule, as the person who created them, with nobody present. - name: Skills description: >- Reusable playbooks for Parley's assistant: a SKILL.md plus optional bundled documents, addressed by slug. - name: Users description: The people in your organization, and the caller. paths: /sessions/{id}/messages: post: tags: - Sessions summary: Send a message description: >- Send a message to a session. An idle assistant starts on it right away; a working one reads it at its next step, so you can steer it mid-task. Returns the session as soon as the message is queued, with status working; get the session until its status is idle, then read the reply with GET /sessions/{id}/messages. Sessions started in Word or Outlook can only be continued there. Returns 409 SESSION_BUSY while the session is being summarized or changed, and 429 USAGE_LIMIT_REACHED when the organization has used its Parley AI allowance for the billing period. operationId: sendSessionMessage parameters: - name: id in: path required: true schema: type: string minLength: 1 description: The session ID. requestBody: required: true content: application/json: schema: type: object properties: message: type: string minLength: 1 maxLength: 100000 description: The message, up to 100,000 characters. required: - message additionalProperties: false responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string minLength: 1 description: The session ID. title: anyOf: - type: string - type: 'null' description: >- The session's title, written by Parley after the first reply unless someone named it, or null until then. status: enum: - working - idle type: string description: >- working: Parley's assistant is working, a message is waiting for it, or it is waiting on subagents it started in the background. idle: the assistant has stopped and is waiting for the next message. origin: enum: - web - word - outlook - automation - api type: string description: >- Where the session was started: web (Parley's web app, or an email to Parley's assistant), word or outlook (the add-in), automation (an automation run), or api (the REST API, MCP, or the CLI). project: anyOf: - $ref: '#/components/schemas/ProjectRef' - type: 'null' description: >- The project the session works in, with that project's files, notes, and linked records as its context, or null for a session across the organization. automation: anyOf: - type: object properties: type: const: automation id: type: string description: Its ID. name: type: string description: The automation name. required: - type - id - name description: The automation's type, ID, and name. - type: 'null' description: The automation whose run started the session, or null. lastRun: anyOf: - type: object properties: status: enum: - running - completed - interrupted - failed type: string description: >- running: in progress. completed: the assistant finished. interrupted: someone stopped it. failed: it ended with an error. startedAt: type: string format: date-time description: When the assistant started. endedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When the assistant stopped, or null while it is running. error: anyOf: - type: object properties: code: anyOf: - type: string - type: 'null' description: >- Machine-readable reason, such as CONTEXT_WINDOW_EXCEEDED, or null. message: type: string description: Human-readable description. required: - code - message - type: 'null' description: Why a failed run failed, or null. required: - status - startedAt - endedAt - error - type: 'null' description: >- The assistant's most recent pass over the session's messages, or null before it starts. url: type: string format: uri description: Where to open the session in Parley. createdAt: type: string format: date-time description: When the session was started. updatedAt: type: string format: date-time description: When the session last changed, such as by a new message. required: - id - title - status - origin - project - automation - lastRun - url - createdAt - updatedAt '400': description: The request was invalid. VALIDATION_FAILED. content: application/json: schema: $ref: '#/components/schemas/ValidationFailedError' '401': description: Missing or invalid credentials. UNAUTHORIZED. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: You don't have permission. FORBIDDEN. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Not found. NOT_FOUND. content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '409': description: The request conflicts with the current state. SESSION_BUSY. content: application/json: schema: $ref: '#/components/schemas/SessionBusyError' '429': description: >- Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS, USAGE_LIMIT_REACHED. content: application/json: schema: oneOf: - $ref: '#/components/schemas/TooManyRequestsError' - $ref: '#/components/schemas/UsageLimitReachedError' components: schemas: ProjectRef: type: object properties: type: const: project id: type: string description: Its ID. name: type: string description: The project name. required: - type - id - name description: The project's type, ID, and name. ValidationFailedError: type: object properties: error: type: object properties: code: type: string const: VALIDATION_FAILED message: type: string examples: - The request is invalid. details: type: object properties: issues: type: array items: type: object properties: path: type: string description: >- Where the problem is, as a dotted path into the input such as accountIds.add.0 or reminder.remindAt. Empty for the input as a whole. message: type: string description: What is wrong with the value. required: - path - message description: Each problem with the input. required: - issues required: - code - message - details required: - error UnauthorizedError: type: object properties: error: type: object properties: code: type: string const: UNAUTHORIZED message: type: string examples: - Missing or invalid credentials. required: - code - message required: - error ForbiddenError: type: object properties: error: type: object properties: code: type: string const: FORBIDDEN message: type: string examples: - You don't have permission to do this. required: - code - message required: - error NotFoundError: type: object properties: error: type: object properties: code: type: string const: NOT_FOUND message: type: string examples: - Not found. required: - code - message required: - error SessionBusyError: type: object properties: error: type: object properties: code: type: string const: SESSION_BUSY message: type: string examples: - >- The session is being summarized or changed. Try again in a few seconds. required: - code - message required: - error TooManyRequestsError: type: object properties: error: type: object properties: code: type: string const: TOO_MANY_REQUESTS message: type: string examples: - Too many requests. required: - code - message required: - error UsageLimitReachedError: type: object properties: error: type: object properties: code: type: string const: USAGE_LIMIT_REACHED message: type: string examples: - The organization has reached its usage limit. required: - code - message required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: A Parley API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.