> ## Documentation Index > Fetch the complete documentation index at: https://docs.crmspark.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Cria ou atualiza um chat DM > Cria ou atualiza uma conversa direta (DM) com um contato. A plataforma é inferida pelo entrypointId (apenas WhatsApp e WhatsApp Lite). O telefone é normalizado automaticamente para o padrão E.164. Se o lead ainda não existir, ele é criado nesta requisição. Se o chat já existir para o mesmo entrypoint e telefone, atualiza o nome do chat quando informado. ## OpenAPI ````yaml /openapi/gateway.json post /v1/chats openapi: 3.0.0 info: title: Spark description: >- Documentação da API pública do Spark CRM. Respostas de erro usam `{ statusCode, code, message }`; trate erros pelo campo `code` (veja catálogo completo abaixo). ## Erros da API Todas as respostas de erro seguem o formato `{ statusCode, code, message }`. O campo **`code`** é estável entre versões — trate erros pelo código, não pela mensagem. | Código | HTTP | Descrição | | --- | ---: | --- | | `API_KEY_MISSING` | 401 | Cabeçalho `X-API-Key` ausente. Inclua a chave em todas as requisições autenticadas. | | `API_KEY_INVALID` | 401 | Prefixo ou valor da API Key não reconhecido. Verifique se copiou a chave correta do painel. | | `API_KEY_WRONG_TYPE` | 401 | O tipo da chave (pública ou privada) não é aceito neste endpoint. | | `DEVELOPERS_DISABLED` | 401 | Habilite o ambiente de desenvolvedores no painel antes de usar a API. | | `SUBSCRIPTION_INACTIVE` | 403 | O tenant não possui plano ativo ou a assinatura está suspensa/cancelada. | | `LEAD_LIMIT_EXCEEDED` | 403 | A operação criaria leads além do limite do plano atual. Faça upgrade ou remova leads. | | `FORM_INACTIVE` | 403 | O formulário existe, mas está desativado e não pode ser exibido nem receber envios. | | `RESOURCE_ACCESS_DENIED` | 403 | O recurso pertence a outro tenant ou a chave não tem escopo para lê-lo. | | `ENTRYPOINT_NOT_FOUND` | 404 | Nenhum entrypoint com o ID informado foi encontrado para o tenant autenticado. | | `FORM_NOT_FOUND` | 404 | Nenhum formulário com o ID público informado foi encontrado para o tenant autenticado. | | `CHAT_NOT_FOUND` | 404 | Nenhum chat com o ID informado foi encontrado para o tenant autenticado. | | `RESOURCE_NOT_FOUND` | 404 | O recurso solicitado não existe ou não está acessível para o tenant autenticado. | | `FORM_ALREADY_SUBMITTED` | 409 | Cada telefone pode enviar apenas uma resposta por formulário. | | `VALIDATION_ERROR` | 400 | Corpo, query ou parâmetros não passaram na validação de schema. | | `INVALID_PHONE` | 400 | O telefone informado não pôde ser normalizado para E.164. | | `ENTRYPOINT_PLATFORM_UNSUPPORTED` | 400 | O entrypoint informado pertence a uma plataforma não suportada pela operação. | | `PLATFORM_UNSUPPORTED` | 400 | Valor de filtro `platform` inválido ou não suportado. | | `FORM_MISSING_ENTRYPOINTS` | 400 | O formulário não possui entrypoints de destino configurados para receber leads. | | `FORM_INVALID_ANSWERS` | 400 | Perguntas ausentes, duplicadas, desconhecidas ou com opções inválidas. | | `FORM_INVALID_DESTINATION` | 400 | Um ou mais entrypoints configurados no formulário são inválidos ou inacessíveis. | | `MEDIA_UPLOAD_EMPTY` | 400 | O upload multipart não incluiu nenhum arquivo. | | `MEDIA_UPLOAD_TOO_MANY_FILES` | 400 | Mais arquivos foram enviados do que o permitido por requisição. | | `MEDIA_FILE_TOO_LARGE` | 400 | Um ou mais arquivos ultrapassam o limite de tamanho. | | `MEDIA_INVALID_FORMAT` | 400 | O tipo MIME ou conteúdo do arquivo não é aceito para upload de mídia. | | `INVALID_REQUEST` | 400 | A combinação de campos ou parâmetros da requisição não é permitida. | | `UNPROCESSABLE_REQUEST` | 422 | A requisição está bem formada, mas não pode ser processada no estado atual. | | `MESSAGE_CAMPAIGN_NOT_ALLOWED` | 422 | O corpo da mensagem referencia campanha, o que não é permitido na API pública. | | `CAMPAIGN_NOT_FOUND` | 404 | Nenhuma campanha com o ID informado foi encontrada para o tenant autenticado. | | `CAMPAIGN_NAME_ALREADY_EXISTS` | 400 | O nome da campanha deve ser único dentro da organização. | | `CAMPAIGN_TEMPLATE_NOT_FOUND` | 404 | O templateId informado não existe ou não pertence ao tenant autenticado. | | `CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH` | 400 | Templates oficiais só podem ser usados em WhatsApp Business ou Instagram. | | `CAMPAIGN_INVALID_FILTERS` | 422 | Um ou mais filtros possuem campo, operador ou valor incompatível. | | `CAMPAIGN_NOT_DRAFT` | 422 | A campanha já foi iniciada, concluída ou cancelada. | | `CAMPAIGN_ALREADY_PROCESSING` | 422 | Aguarde a conclusão ou cancele a execução atual antes de iniciar novamente. | | `CAMPAIGN_MISSING_COMMON_VARIABLES` | 400 | Informe commonVariables com as chaves var1, var2, etc. exigidas pelo template. | | `CAMPAIGN_SIZE_LIMIT_EXCEEDED` | 422 | Reduza o público-alvo ou ajuste os filtros antes de iniciar. | | `MESSAGE_TEMPLATE_NOT_FOUND` | 404 | Nenhum modelo de mensagem com o ID informado foi encontrado. | | `RATE_LIMIT_EXCEEDED` | 429 | Muitas requisições em curto intervalo. Aguarde e tente novamente. | | `INTERNAL_ERROR` | 500 | Falha inesperada no servidor. Se persistir, contate o suporte. | Schema: [`PublicApiErrorResponse`](#/components/schemas/PublicApiErrorResponse). version: '1.0' contact: {} servers: - url: https://gateway.crmspark.com.br description: Oficial security: [] tags: [] paths: /v1/chats: post: tags: - Chats summary: Cria ou atualiza um chat DM description: >- Cria ou atualiza uma conversa direta (DM) com um contato. A plataforma é inferida pelo entrypointId (apenas WhatsApp e WhatsApp Lite). O telefone é normalizado automaticamente para o padrão E.164. Se o lead ainda não existir, ele é criado nesta requisição. Se o chat já existir para o mesmo entrypoint e telefone, atualiza o nome do chat quando informado. operationId: chats_upsert_v1 parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateChatBodyDto' responses: '200': description: >- Chat já existia para este entrypoint e telefone; IDs retornados sem criar duplicata. O nome do chat é atualizado quando informado. content: application/json: schema: $ref: '#/components/schemas/CreateChatResponseSchema' '201': description: |- IDs do chat e do lead. Chat criado com sucesso. content: application/json: schema: $ref: '#/components/schemas/CreateChatResponseSchema' '400': description: >- - `VALIDATION_ERROR` (400): Corpo, query ou parâmetros não passaram na validação de schema. - `INVALID_PHONE` (400): O telefone informado não pôde ser normalizado para E.164. - `ENTRYPOINT_PLATFORM_UNSUPPORTED` (400): O entrypoint informado pertence a uma plataforma não suportada pela operação. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: VALIDATION_ERROR: value: statusCode: 400 code: VALIDATION_ERROR message: Dados da requisição inválidos. INVALID_PHONE: value: statusCode: 400 code: INVALID_PHONE message: >- Telefone inválido. Informe um número com DDI e DDD válidos. ENTRYPOINT_PLATFORM_UNSUPPORTED: value: statusCode: 400 code: ENTRYPOINT_PLATFORM_UNSUPPORTED message: >- Este endpoint suporta apenas pontos de entrada do WhatsApp e WhatsApp Lite. '401': description: >- - `API_KEY_MISSING` (401): Cabeçalho `X-API-Key` ausente. Inclua a chave em todas as requisições autenticadas. - `API_KEY_INVALID` (401): Prefixo ou valor da API Key não reconhecido. Verifique se copiou a chave correta do painel. - `API_KEY_WRONG_TYPE` (401): O tipo da chave (pública ou privada) não é aceito neste endpoint. - `DEVELOPERS_DISABLED` (401): Habilite o ambiente de desenvolvedores no painel antes de usar a API. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: API_KEY_MISSING: value: statusCode: 401 code: API_KEY_MISSING message: API Key não fornecida. API_KEY_INVALID: value: statusCode: 401 code: API_KEY_INVALID message: API Key inválida. API_KEY_WRONG_TYPE: value: statusCode: 401 code: API_KEY_WRONG_TYPE message: API Key não autorizada a acessar este recurso. DEVELOPERS_DISABLED: value: statusCode: 401 code: DEVELOPERS_DISABLED message: >- O ambiente de desenvolvedores não está habilitado para este tenant. '403': description: >- - `SUBSCRIPTION_INACTIVE` (403): O tenant não possui plano ativo ou a assinatura está suspensa/cancelada. - `LEAD_LIMIT_EXCEEDED` (403): A operação criaria leads além do limite do plano atual. Faça upgrade ou remova leads. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: SUBSCRIPTION_INACTIVE: value: statusCode: 403 code: SUBSCRIPTION_INACTIVE message: Sua organização não possui uma assinatura ativa. LEAD_LIMIT_EXCEEDED: value: statusCode: 403 code: LEAD_LIMIT_EXCEEDED message: Limite de leads excedido. '404': description: >- - `ENTRYPOINT_NOT_FOUND` (404): Nenhum entrypoint com o ID informado foi encontrado para o tenant autenticado. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: ENTRYPOINT_NOT_FOUND: value: statusCode: 404 code: ENTRYPOINT_NOT_FOUND message: Ponto de entrada não encontrado. '429': description: >- - `RATE_LIMIT_EXCEEDED` (429): Muitas requisições em curto intervalo. Aguarde e tente novamente. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: RATE_LIMIT_EXCEEDED: value: statusCode: 429 code: RATE_LIMIT_EXCEEDED message: Limite de requisições excedido. security: - api-key: [] components: schemas: CreateChatBodyDto: type: object properties: entrypointId: type: string description: >- ID do ponto de entrada (canal) no Spark. A plataforma é inferida automaticamente (WhatsApp ou WhatsApp Lite). phone: type: string minLength: 3 maxLength: 40 description: >- Telefone do contato em qualquer formato comum. Será normalizado para o padrão E.164 da plataforma (ex.: 5511999999999). name: description: >- Nome exibido no chat (conversa DM). Se omitido, o chat é criado sem nome personalizado. Ao reutilizar um chat existente, atualiza o nome quando informado. type: string minLength: 1 maxLength: 255 triggerAutomations: default: true description: >- Se verdadeiro (padrão), dispara automações ao criar um novo lead ou chat. type: boolean required: - entrypointId - phone additionalProperties: false CreateChatResponseSchema: type: object properties: chatId: type: string description: ID do chat no Spark. leadId: type: string description: >- ID do lead vinculado ao chat (criado nesta requisição ou já existente). required: - chatId - leadId additionalProperties: false PublicApiErrorResponse: type: object required: - statusCode - code - message properties: statusCode: type: integer description: Código HTTP da resposta. example: 400 code: type: string description: >- Código estável e legível por máquina. Use este campo — não parseie `message` — para tratar erros no cliente. enum: - API_KEY_MISSING - API_KEY_INVALID - API_KEY_WRONG_TYPE - DEVELOPERS_DISABLED - SUBSCRIPTION_INACTIVE - LEAD_LIMIT_EXCEEDED - FORM_INACTIVE - RESOURCE_ACCESS_DENIED - ENTRYPOINT_NOT_FOUND - FORM_NOT_FOUND - CHAT_NOT_FOUND - RESOURCE_NOT_FOUND - FORM_ALREADY_SUBMITTED - VALIDATION_ERROR - INVALID_PHONE - ENTRYPOINT_PLATFORM_UNSUPPORTED - PLATFORM_UNSUPPORTED - FORM_MISSING_ENTRYPOINTS - FORM_INVALID_ANSWERS - FORM_INVALID_DESTINATION - MEDIA_UPLOAD_EMPTY - MEDIA_UPLOAD_TOO_MANY_FILES - MEDIA_FILE_TOO_LARGE - MEDIA_INVALID_FORMAT - INVALID_REQUEST - UNPROCESSABLE_REQUEST - MESSAGE_CAMPAIGN_NOT_ALLOWED - CAMPAIGN_NOT_FOUND - CAMPAIGN_NAME_ALREADY_EXISTS - CAMPAIGN_TEMPLATE_NOT_FOUND - CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH - CAMPAIGN_INVALID_FILTERS - CAMPAIGN_NOT_DRAFT - CAMPAIGN_ALREADY_PROCESSING - CAMPAIGN_MISSING_COMMON_VARIABLES - CAMPAIGN_SIZE_LIMIT_EXCEEDED - MESSAGE_TEMPLATE_NOT_FOUND - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR message: type: string description: Mensagem legível em português, útil para logs e exibição ao usuário. securitySchemes: api-key: type: apiKey in: header name: X-API-Key ````