> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt > Use this file to discover all available pages before exploring further. # Enviar mensagem do visitante > Mensagem do visitante: entra na caixa de entrada como qualquer canal (o primeiro envio abre o atendimento na fila do webchat). Texto em JSON (`text`) ou arquivo em multipart (`media`, até 10 MB; imagem, áudio, vídeo, PDF, DOCX, XLSX ou ZIP). Use `Idempotency-Key` para não duplicar em reenvio. Resposta a uma mensagem interativa: `interactiveReply` com o `id` da mensagem e o `id` da opção escolhida (de `options` ou de `interactive`). O título gravado vem da própria mensagem, como no WhatsApp: a resposta chega ao atendimento e à automação como texto (o título da opção), citando a interativa. Pedido de localização: `location` com `latitude` e `longitude`, gravada como a localização do WhatsApp. Com `interactiveReply` ou `location`, o `text` é ignorado. Faltando dado obrigatório: 422 `ERR_WEBCHAT_VISITOR_DATA_REQUIRED`, com os campos na `message` (ex.: `name,phone`). Opção que não está na mensagem (ou mensagem que o visitante não vê): 422 `ERR_WEBCHAT_INTERACTIVE_REPLY_INVALID`. Coordenada inválida: 422 `ERR_WEBCHAT_LOCATION_INVALID`. Sessão encerrada: 410. ## OpenAPI ````yaml /api-reference/openapi.yaml post /webchat/{slug}/sessions/{sessionId}/messages openapi: 3.0.3 info: title: Connecta DESK API pública version: 1.0.0 description: > API pública do Connecta DESK, disponível em `/api/v1`. O acesso é feito com um token gerado no módulo de tokens. Cada token tem permissões por **módulo × método**, e toda leitura de lista é paginada. ## Autenticação ``` Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` O token pertence a uma **empresa**, e não a um usuário. A empresa usada é sempre a do token, então enviar `companyId` no corpo não tem efeito. Token ausente, inválido, revogado ou expirado recebe a mesma resposta `401`. ## Ordem de verificação 1. **token** → `401` 2. **empresa ativa** → `403` 3. **API habilitada no plano** → `403 ERR_API_NOT_ENABLED` (não se aplica a on-premise) 4. **rate limit da empresa** → `429` 5. **permissão do token** → `403 ERR_API_FORBIDDEN_SCOPE` ## Ids de usuário Todo id de usuário na API é o id do usuário **nesta empresa**, o mesmo que `GET /users` devolve. Vale para o que a API responde (`user.id`, `assignedTo.id`, `userCreated.id`) e para o que ela aceita (`userId`, `userIds`, `assignedToUserId` e o `{id}` das rotas de usuário). A mesma pessoa pode trabalhar em várias empresas, com nome e perfil diferentes em cada uma, e tem um id diferente em cada empresa. Um id que não pertence a esta empresa responde `404`, com a mesma mensagem de um id inexistente. ## Paginação Todo `GET` de lista é paginado. O `meta` traz apenas `page`, `perPage` e `hasMore`, sem o total de registros. Para percorrer tudo, avance `page` enquanto `hasMore` for `true`. ## Idempotência Opcional em `POST`/`PUT`, pelo header `Idempotency-Key`. Se você repetir a chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada (com `Idempotent-Replay: true`). Com a mesma chave e um corpo diferente, a resposta é `409`. servers: - url: https://api.connectadesk.com/api/v1 description: Produção security: - apiToken: [] tags: - name: contacts description: Cadastro de contatos, campos extras e origem de marketing. - name: tickets x-displayName: Conversas description: Abertura, transferência, encerramento e qualificação de conversas. - name: messages description: Envio assíncrono e leitura de mensagens. - name: tags description: Tags e vínculo com atendimentos. - name: queues description: Filas de atendimento e seus atendentes. - name: wrapups description: Tipos de qualificação. - name: users description: Atendentes e administradores. - name: schedules description: Mensagens programadas. - name: quick-messages description: Respostas rápidas. - name: campaigns description: Disparos em massa. - name: crm description: Painéis, etapas, cards e indicadores. - name: channels description: Canais (somente leitura). - name: reports description: Relatórios e dashboards. - name: products description: Catálogo de produtos, categorias e desempenho nas vendas. - name: custom-fields description: >- Campos personalizados de contato e de card, e variáveis globais da empresa. - name: profiles description: Perfis de permissões da empresa (somente leitura). - name: webchat description: >- Webchat nativo pelo seu sistema: abrir sessão de um visitante, enviar e ler mensagens. O token precisa do escopo `webchat` (GET e POST). paths: /webchat/{slug}/sessions/{sessionId}/messages: parameters: - name: slug in: path required: true schema: type: string example: site-institucional-3f9a - name: sessionId in: path required: true schema: type: string format: uuid example: 1b0f9a52-3c8e-4f0e-9d1c-6a1c0e7b2f44 post: tags: - webchat summary: Enviar mensagem do visitante description: > Mensagem do visitante: entra na caixa de entrada como qualquer canal (o primeiro envio abre o atendimento na fila do webchat). Texto em JSON (`text`) ou arquivo em multipart (`media`, até 10 MB; imagem, áudio, vídeo, PDF, DOCX, XLSX ou ZIP). Use `Idempotency-Key` para não duplicar em reenvio. Resposta a uma mensagem interativa: `interactiveReply` com o `id` da mensagem e o `id` da opção escolhida (de `options` ou de `interactive`). O título gravado vem da própria mensagem, como no WhatsApp: a resposta chega ao atendimento e à automação como texto (o título da opção), citando a interativa. Pedido de localização: `location` com `latitude` e `longitude`, gravada como a localização do WhatsApp. Com `interactiveReply` ou `location`, o `text` é ignorado. Faltando dado obrigatório: 422 `ERR_WEBCHAT_VISITOR_DATA_REQUIRED`, com os campos na `message` (ex.: `name,phone`). Opção que não está na mensagem (ou mensagem que o visitante não vê): 422 `ERR_WEBCHAT_INTERACTIVE_REPLY_INVALID`. Coordenada inválida: 422 `ERR_WEBCHAT_LOCATION_INVALID`. Sessão encerrada: 410. requestBody: required: true content: application/json: examples: texto: summary: Texto value: text: Olá, gostaria de um orçamento resposta: summary: Responder a uma mensagem value: text: Pode ser na terça quotedMessageId: 6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f opcao: summary: Escolher uma opção de mensagem interativa value: interactiveReply: messageId: 6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f optionId: cartao localizacao: summary: Enviar localização value: location: latitude: -23.561399 longitude: -46.656571 quotedMessageId: 6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f schema: type: object properties: text: type: string maxLength: 4096 quotedMessageId: type: string description: >- Mensagem da conversa que esta responde (citada). Mensagem que o visitante não vê é ignorada. interactiveReply: type: object description: Escolha numa mensagem interativa da empresa. required: - messageId - optionId properties: messageId: type: string description: Id da mensagem interativa. optionId: type: string description: Id da opção (botão, linha da lista ou botão do cartão). location: type: object description: >- Localização do visitante (resposta a um pedido de localização). required: - latitude - longitude properties: latitude: type: number minimum: -90 maximum: 90 longitude: type: number minimum: -180 maximum: 180 multipart/form-data: schema: type: object properties: media: type: string format: binary text: type: string quotedMessageId: type: string responses: '201': description: Criada content: application/json: schema: type: object properties: data: type: object properties: message: $ref: '#/components/schemas/WebchatMessage' ticketId: type: integer '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' components: schemas: WebchatMessage: type: object properties: id: type: string example: 6f1d2c1e-8a8b-4f35-a1e6-1f2f3c4d5e6f body: type: string description: >- Texto da mensagem. Numa mensagem interativa, só o corpo (cabeçalho e rodapé vêm em `interactive`). example: Olá, gostaria de um orçamento fromVisitor: type: boolean example: true origin: type: string enum: - visitor - agent - bot - automation - api example: visitor agentName: type: string nullable: true example: null ack: type: integer description: 1 enviada, 3 entregue ao widget, 4 lida. example: 1 mediaUrl: type: string nullable: true example: null mediaType: type: string nullable: true description: >- `image`, `video`, `audio`, `application` ou `locationMessage` (localização). example: null fileName: type: string nullable: true example: null options: type: array description: >- Opções de resposta da mensagem interativa (botões, linhas da lista e botões dos cartões). Para responder, use `interactiveReply` com o `id` da opção. items: type: object properties: id: type: string title: type: string example: [] interactive: $ref: '#/components/schemas/WebchatInteractive' location: $ref: '#/components/schemas/WebchatLocation' quoted: $ref: '#/components/schemas/WebchatQuoted' isDeleted: type: boolean example: false isEdited: type: boolean example: false createdAt: type: string format: date-time example: '2026-10-01T13:45:00.000Z' WebchatInteractive: type: object nullable: true description: > Mensagem interativa enviada pela empresa, pronta para desenhar (o widget desenha como no WhatsApp). `null` nas mensagens comuns e nas do visitante. | `type` | Ação | | --- | --- | | `button` | `buttons`: botões de resposta | | `list` | `list.button` abre a lista; `list.sections[].rows[]` são as opções | | `cta_url` | `link`: botão que abre `link.url` | | `location_request` | pedido de localização: responda com `location` | | `carousel` | `cards[]`: mídia, texto e botões de resposta ou de link | properties: type: type: string enum: - button - list - cta_url - location_request - carousel example: button header: type: object nullable: true description: >- Cabeçalho: `{ type: text, text }`, `{ type: image|video, url }` ou `{ type: document, url, fileName }`. properties: type: type: string enum: - text - image - video - document text: type: string url: type: string fileName: type: string nullable: true body: type: string example: Como prefere pagar? footer: type: string nullable: true example: null buttons: type: array items: type: object properties: id: type: string title: type: string example: - id: pix title: Pix - id: cartao title: Cartão list: type: object properties: button: type: string example: Ver opções sections: type: array items: type: object properties: title: type: string nullable: true rows: type: array items: type: object properties: id: type: string title: type: string description: type: string nullable: true link: type: object properties: text: type: string example: Rastrear pedido url: type: string example: https://loja.com.br/pedidos/1234 cards: type: array items: type: object properties: header: type: object nullable: true properties: type: type: string enum: - image - video url: type: string body: type: string buttons: type: array items: type: object properties: id: type: string title: type: string link: type: object nullable: true properties: text: type: string url: type: string example: type: button header: null body: Como prefere pagar? footer: null buttons: - id: pix title: Pix - id: cartao title: Cartão WebchatLocation: type: object nullable: true description: >- Localização (mensagem com `mediaType: locationMessage`). `null` nas demais. properties: latitude: type: number example: -23.561399 longitude: type: number example: -46.656571 url: type: string description: Link do mapa. example: https://maps.google.com/maps?q=-23.561399%2C-46.656571&z=17 example: null WebchatQuoted: type: object nullable: true description: >- Mensagem respondida (citada). Ausente quando a citação não foi carregada; `null` quando não há ou o visitante não pode vê-la. properties: id: type: string body: type: string fromVisitor: type: boolean mediaType: type: string nullable: true fileName: type: string nullable: true isDeleted: type: boolean example: null Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Código fixo do erro, para você tratar cada caso no seu sistema. example: ERR_API_FORBIDDEN_SCOPE message: type: string details: {} responses: Unauthorized: description: Token ausente, inválido, revogado ou expirado. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_UNAUTHORIZED message: Token de API ausente ou inválido. Forbidden: description: Empresa inativa, API não habilitada no plano ou permissão insuficiente. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_FORBIDDEN_SCOPE message: >- O token não tem permissão para este método neste módulo. A mensagem real nomeia os dois. NotFound: description: >- O recurso não existe ou pertence a outra empresa. Por segurança, a resposta é a mesma nos dois casos. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_NOT_FOUND message: Registro não encontrado. UnprocessableEntity: description: >- O corpo está bem formado, mas falta um campo obrigatório ou algum valor não é aceito. Por exemplo, `application` diferente de `contact`/`card`, `orderedIds` vazio ou `name` em branco. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_VALIDATION message: >- O parâmetro `application` é obrigatório e aceita "contact" ou "card". securitySchemes: apiToken: type: http scheme: bearer description: Token da API no formato `sk_live_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.