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

# Capturar atendimento

> Um usuário assume a conversa que está na fila. Recusada se a conversa já está `Em Atendimento` — para tirar de um atendente e passar a outro, use **Transferir para usuário**. Scope: `chats:capture`.

<Warning>
  A captura é recusada com `400` se a conversa já está `Em Atendimento`. Para reatribuir, use [Transferir para usuário](/api-reference/endpoint/transferir-para-usuario).
</Warning>


## OpenAPI

````yaml POST /channel-api/chats/{id}/capture
openapi: 3.1.0
info:
  title: Zazz Chat — Channel API
  description: >-
    Channel API do Zazz Chat: envio de mensagens, roteamento de conversas e
    webhook de eventos. Há duas credenciais: a chave de API do canal (header
    `x-channel-api-key`) e a API key de conta (header `Authorization: ApiKey
    <token>`), com scopes e canais permitidos.
  version: 1.0.0
servers:
  - url: https://{host}
    description: Back-end do Zazz Chat
    variables:
      host:
        default: chat.zazzinternet.com
        description: Host do back-end da sua instalação do Zazz Chat
security:
  - channelApiKey: []
paths:
  /channel-api/chats/{id}/capture:
    post:
      summary: Capturar atendimento
      description: >-
        Um usuário assume a conversa que está na fila. Recusada se a conversa já
        está `Em Atendimento` — para tirar de um atendente e passar a outro, use
        **Transferir para usuário**. Scope: `chats:capture`.
      parameters:
        - name: id
          in: path
          required: true
          description: ID do chat (ObjectId).
          schema:
            type: string
            example: 66f2a1c9e4b0a1b2c3d4e5f6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptureChatRequest'
            example:
              userId: 66f1f0c2e4b0a1b2c3d4e200
      responses:
        '200':
          description: Conversa após a captura.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSummary'
        '400':
          description: Usuário inexistente/cancelado ou conversa já em atendimento.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 400
                message: Chat ja esta em atendimento e nao pode ser capturado novamente
                error: Bad Request
        '401':
          description: >-
            Nenhuma credencial válida (API key revogada, inexistente ou header
            ausente).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 401
                message: Credencial ausente ou inválida
                error: Unauthorized
        '404':
          description: >-
            Credencial ausente/inválida para esta rota, key sem o scope exigido,
            chat inexistente ou fora dos canais permitidos da key. A API não
            diferencia os casos para não revelar a existência do recurso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 404
                message: Not Found
                error: Not Found
        '409':
          description: >-
            O chat está sendo processado por outra operação neste momento. Tente
            de novo em alguns segundos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 409
                message: O chat ja foi capturado por outro usuario.
                error: Conflict
        '429':
          description: Limite de 120 requisições por minuto por API key excedido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 429
                message: Rate limit exceeded. Maximum 120 requests per 60s per API key.
      security:
        - accountApiKey: []
components:
  schemas:
    CaptureChatRequest:
      type: object
      required:
        - userId
      properties:
        userId:
          type: string
          description: Usuário que assume o atendimento.
    ChatSummary:
      type: object
      properties:
        id:
          type: string
          example: 66f2a1c9e4b0a1b2c3d4e5f6
        status:
          type: string
          example: open
        queue:
          type: string
          description: >-
            Fila atual: `Espera` (aguardando atendente da equipe), `Em
            Atendimento`, `Automação`, `API` ou a fila configurada no canal.
          example: Espera
        channelId:
          type:
            - string
            - 'null'
          example: 66f1f0c2e4b0a1b2c3d4e001
        teamId:
          type:
            - string
            - 'null'
          example: 66f1f0c2e4b0a1b2c3d4e100
        userId:
          type:
            - string
            - 'null'
          description: Atendente atual; `null` quando ninguém está atendendo.
          example: null
        contact:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
            name:
              type:
                - string
                - 'null'
              example: Cliente
            value:
              type:
                - string
                - 'null'
              description: 'Identificador do contato no canal (ex.: telefone).'
              example: '554396647639'
        unreadMessages:
          type: integer
          example: 2
        lastMessage:
          type:
            - object
            - 'null'
          description: Resumo da última mensagem (`origin`, `content`).
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    channelApiKey:
      type: apiKey
      in: header
      name: x-channel-api-key
      description: >-
        Chave de API do canal, gerada na aba **API** das configurações do canal
        (Dashboard → Suporte → Canais). A chave é exibida uma única vez ao ser
        gerada; gerar uma nova invalida a anterior.
    accountApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key de conta, no formato `ApiKey <token>` (ex.: `ApiKey
        zk_live_...`). Criada em **Configurações → API Keys** por um usuário com
        a permissão `api_keys:manage`. O token é exibido uma única vez. Cada
        rota exige um scope; key sem o scope, ou recurso fora dos canais
        permitidos da key, responde `404`.

````