> ## Documentation Index
> Fetch the complete documentation index at: https://help.ciarem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Assign a conversation

> Assign the conversation to a member, or unassign it, and return it.

With `keep_ai: true` the AI keeps answering while the member owns the
conversation, as with "keep it in my inbox" when handing a chat to the AI.
When the AI hands off, the conversation goes to that member, unless an
assignment rule names someone else. If a person already took the
conversation over, it moves to the new member and stays with a person.

Without `keep_ai` this works like assigning from the inbox: the member takes
the conversation over and the AI stops, also when the member already owned
it while the AI answered.

Unassigning sends the conversation back to the queue for automatic
assignment, or, with `keep_ai`, leaves it with the AI. A conversation with
no assignee that the AI is answering stays with the AI either way.

A new assignee gets the conversation unread, and a `conversation.assigned`
webhook is sent. Assigning the current assignee sends no webhook.

422 `member_not_found` when no current member of the organization has that
email. 422 `assignee_is_viewer` when that member has the Viewer role,
which reads but takes no chats. 409 `conversation_resolved` when the conversation
is resolved: the contact's next message opens a new conversation, so assign
that one.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/conversations/{conversation_id}/assign
openapi: 3.1.0
info:
  title: Ciarem API
  version: v1
  description: >
    The Ciarem public API. Authenticate every request with an org-bound API key

    (created in Settings → API keys; Growth or Scale plan, or free trial) sent
    as a bearer token:

    `Authorization: Bearer oak_…`.


    Compatibility: this is an early, fast-moving API. Most changes are

    additive (new endpoints, new optional params, new response fields, new

    enum/string values) — clients must tolerate unknown fields and unknown

    string values. Every contract change is listed in the changelog at

    help.ciarem.ai.
servers:
  - url: https://api.ciarem.ai
security:
  - apiKey: []
tags:
  - name: Account
    description: The organization behind the API key.
  - name: Contacts
    description: People in the CRM — create, read, update, delete.
  - name: CRM
    description: 'The shape of the CRM: custom properties and funnel stages.'
  - name: Catalogs
    description: 'Products and services: catalogs, their properties, records and variants.'
  - name: Conversations
    description: Read conversations and their messages, and assign them to members.
  - name: WhatsApp numbers
    description: The connected numbers a send can go out from.
  - name: WhatsApp templates
    description: Message templates, and what each one needs filled before it can be sent.
  - name: Broadcasts
    description: Send a template, and follow what happened to every recipient.
  - name: Webhooks
    description: Have Ciarem POST events to your server as they happen, instead of polling.
paths:
  /v1/conversations/{conversation_id}/assign:
    post:
      tags:
        - Conversations
      summary: Assign a conversation
      description: >-
        Assign the conversation to a member, or unassign it, and return it.


        With `keep_ai: true` the AI keeps answering while the member owns the

        conversation, as with "keep it in my inbox" when handing a chat to the
        AI.

        When the AI hands off, the conversation goes to that member, unless an

        assignment rule names someone else. If a person already took the

        conversation over, it moves to the new member and stays with a person.


        Without `keep_ai` this works like assigning from the inbox: the member
        takes

        the conversation over and the AI stops, also when the member already
        owned

        it while the AI answered.


        Unassigning sends the conversation back to the queue for automatic

        assignment, or, with `keep_ai`, leaves it with the AI. A conversation
        with

        no assignee that the AI is answering stays with the AI either way.


        A new assignee gets the conversation unread, and a
        `conversation.assigned`

        webhook is sent. Assigning the current assignee sends no webhook.


        422 `member_not_found` when no current member of the organization has
        that

        email. 422 `assignee_is_viewer` when that member has the Viewer role,

        which reads but takes no chats. 409 `conversation_resolved` when the
        conversation

        is resolved: the contact's next message opens a new conversation, so
        assign

        that one.
      operationId: assign_endpoint_v1_conversations__conversation_id__assign_post
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            title: Conversation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicConversationAssign'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicConversationDetail'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '401':
          description: >-
            No usable credential: `missing_bearer_token` (no `Authorization:
            Bearer`) or `invalid_api_key` (unknown or revoked key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
        '403':
          description: >-
            The credential is real but not allowed here: `api_key_required` (a
            session token rather than an `oak_` key), `plan_upgrade_required`
            (the plan doesn't include API access — upgrade to Growth or Scale),
            `trial_expired` (the free trial ended without a card — subscribe to
            keep the key working), or `subscription_required` (the subscription
            is canceled or suspended).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Over the organization's request budget (`rate_limited`); the budget
            depends on the plan. Or the API key already has 8 requests running
            (`too_many_concurrent_requests`); that request was not run and does
            not count against the budget, `Retry-After` is a fixed 1 s and the
            `X-RateLimit-*` headers are absent. `Retry-After` says how many
            seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying: until the window resets for
                `rate_limited`, a fixed 1 s for `too_many_concurrent_requests`.
              schema:
                type: integer
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '503':
          description: >-
            The API is at capacity (`server_busy`). The request was not run and
            does not count against the budget; retry after `Retry-After`
            seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
components:
  schemas:
    PublicConversationAssign:
      properties:
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: >-
            The member to assign, by the email they sign in with. `null`
            unassigns.
        keep_ai:
          type: boolean
          title: Keep Ai
          description: >-
            Keep the AI answering. Without it, the member takes the chat over
            and the AI stops, as when assigning from the inbox.
          default: false
      additionalProperties: false
      type: object
      required:
        - email
      title: PublicConversationAssign
    PublicConversationDetail:
      properties:
        id:
          type: string
          title: Id
        channel_kind:
          $ref: '#/components/schemas/ChannelKind'
        channel_id:
          type: string
          title: Channel Id
        external_id:
          type: string
          title: External Id
        display_name:
          type: string
          title: Display Name
        handled_by:
          $ref: '#/components/schemas/ConversationHandler'
        status:
          $ref: '#/components/schemas/ConversationStatus'
        assignee_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Assignee Id
          description: >-
            Member id (`mbr_…`) of the member the conversation is assigned to:
            `id` in `GET /v1/members`.
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
        contact_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Contact Id
        last_inbound_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Inbound At
        last_message_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Message At
        resolved_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Resolved At
        created_at:
          type: string
          format: date-time
          title: Created At
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - channel_kind
        - channel_id
        - external_id
        - display_name
        - handled_by
        - status
        - assignee_id
        - team_id
        - contact_id
        - last_inbound_at
        - last_message_at
        - resolved_at
        - created_at
        - summary
        - updated_at
      title: PublicConversationDetail
    PublicError:
      description: An error whose `detail` is a stable, machine-readable code.
      properties:
        detail:
          title: Detail
          type: string
      required:
        - detail
      title: PublicError
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChannelKind:
      type: string
      enum:
        - whatsapp
        - instagram
        - messenger
        - webchat
        - email
      title: ChannelKind
      description: Connected messaging channel kinds. Stored in `channels.kind`.
    ConversationHandler:
      type: string
      enum:
        - ai
        - human
        - whatsapp_app
      title: ConversationHandler
      description: >-
        Who is currently handling a conversation. The AI runs only while `ai`;

        while `human` or `whatsapp_app` inbound messages bypass the AI and
        surface in

        the inbox.
    ConversationStatus:
      type: string
      enum:
        - open
        - resolved
      title: ConversationStatus
      description: >-
        Lifecycle of a conversation. `resolved` is terminal: the contact's next

        message opens a fresh conversation. There is no `expired` value:
        WhatsApp

        24h "expiry" is a derived window state (`now - last_inbound_at >= 24h`),

        not a lifecycle status — an expired thread is still `open`. (`closed`
        was

        dropped by migration 0200: nothing distinguished it from `resolved`.)
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per window, shared across the org's keys.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: When the window resets, as a Unix timestamp in seconds.
      schema:
        type: integer
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An org API key: `Authorization: Bearer oak_…`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.