{"openapi":"3.1.0","info":{"title":"API do conecta/ai","version":"1.0.0","description":"API REST para o sistema do provedor ler e, nas próximas versões, agir sobre o atendimento no conecta/ai. Toda requisição leva uma chave de API no cabeçalho Authorization e só enxerga a organização dona da chave. O limite é de 120 requisições por minuto por organização, somando todas as chaves.","contact":{"name":"Suporte conecta/ai","url":"https://help.conectaai.io/suporte"}},"servers":[{"url":"https://app.conectaai.io/api/v1","description":"Produção"}],"security":[{"chaveDeApi":[]}],"tags":[{"name":"Conversas","description":"Atendimentos e as mensagens trocadas neles, em todos os canais."},{"name":"Contatos","description":"As pessoas com quem a organização conversa e os canais de cada uma."},{"name":"Etiquetas","description":"As etiquetas que a organização usa para classificar conversas."},{"name":"Agentes","description":"Os agentes de IA que atendem pela organização."}],"paths":{"/conversations":{"get":{"operationId":"listConversations","tags":["Conversas"],"summary":"Listar conversas","description":"Lista as conversas da organização, da mais recente para a mais antiga (pela data de início). Use `updated_after` para sincronizar só o que mudou desde a última leitura.\n\nPermissão exigida na chave: `conversas:read`.","x-required-scope":"conversas:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Quantos itens por página, de 1 a 100. Padrão 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Valor de `next_cursor` da página anterior. Omita para a primeira página.","schema":{"type":"string","maxLength":512}},{"name":"status","in":"query","required":false,"description":"Só conversas nesta situação.","schema":{"type":"string","enum":["open","pending","snoozed","resolved","closed"]}},{"name":"channel","in":"query","required":false,"description":"Só conversas deste canal.","schema":{"type":"string","enum":["whatsapp","voice","instagram","messenger","telegram","email","sms","webchat","app"]}},{"name":"contact_id","in":"query","required":false,"description":"Só conversas deste contato.","schema":{"type":"string","maxLength":64}},{"name":"created_after","in":"query","required":false,"description":"Só conversas iniciadas a partir deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z.","schema":{"type":"string"}},{"name":"created_before","in":"query","required":false,"description":"Só conversas iniciadas antes deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z.","schema":{"type":"string"}},{"name":"updated_after","in":"query","required":false,"description":"Só conversas alteradas a partir deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Passe em `cursor` para buscar a próxima página. `null` quando não há mais itens."}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"description":"`invalid_parameter`: Parâmetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: Escopo insuficiente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{id}":{"get":{"operationId":"getConversation","tags":["Conversas"],"summary":"Ler uma conversa","description":"Devolve uma conversa da organização pelo identificador.\n\nPermissão exigida na chave: `conversas:read`.","x-required-scope":"conversas:read","parameters":[{"name":"id","in":"path","required":true,"description":"Identificador do recurso.","schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Sucesso.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"401":{"description":"`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: Escopo insuficiente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: Recurso não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{id}/messages":{"get":{"operationId":"listConversationMessages","tags":["Conversas"],"summary":"Listar mensagens de uma conversa","description":"Lista as mensagens de uma conversa em ordem cronológica, da primeira para a última. Notas internas da equipe não aparecem.\n\nPermissão exigida na chave: `conversas:read`.","x-required-scope":"conversas:read","parameters":[{"name":"id","in":"path","required":true,"description":"Identificador do recurso.","schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"limit","in":"query","required":false,"description":"Quantos itens por página, de 1 a 100. Padrão 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Valor de `next_cursor` da página anterior. Omita para a primeira página.","schema":{"type":"string","maxLength":512}}],"responses":{"200":{"description":"Sucesso.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Passe em `cursor` para buscar a próxima página. `null` quando não há mais itens."}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"description":"`invalid_parameter`: Parâmetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: Escopo insuficiente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: Recurso não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"get":{"operationId":"listContacts","tags":["Contatos"],"summary":"Listar contatos","description":"Lista os contatos da organização, do mais recente para o mais antigo. Para achar um contato pelo telefone, use `phone`.\n\nPermissão exigida na chave: `contatos:read`.","x-required-scope":"contatos:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Quantos itens por página, de 1 a 100. Padrão 50.","schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"Valor de `next_cursor` da página anterior. Omita para a primeira página.","schema":{"type":"string","maxLength":512}},{"name":"status","in":"query","required":false,"description":"Só contatos nesta situação.","schema":{"type":"string","enum":["customer","lead","former_customer","prospect","contact"]}},{"name":"phone","in":"query","required":false,"description":"Só o contato com este telefone, com DDI. Pontuação é ignorada: +55 (11) 98765-4321 vale.","schema":{"type":"string","maxLength":32}},{"name":"updated_after","in":"query","required":false,"description":"Só contatos alterados a partir deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z.","schema":{"type":"string"}}],"responses":{"200":{"description":"Sucesso.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Passe em `cursor` para buscar a próxima página. `null` quando não há mais itens."}},"required":["data","next_cursor"],"additionalProperties":false}}}},"400":{"description":"`invalid_parameter`: Parâmetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: Escopo insuficiente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{id}":{"get":{"operationId":"getContact","tags":["Contatos"],"summary":"Ler um contato","description":"Devolve um contato da organização pelo identificador, com os canais dele.\n\nPermissão exigida na chave: `contatos:read`.","x-required-scope":"contatos:read","parameters":[{"name":"id","in":"path","required":true,"description":"Identificador do recurso.","schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Sucesso.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"401":{"description":"`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: Escopo insuficiente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: Recurso não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tags":{"get":{"operationId":"listTags","tags":["Etiquetas"],"summary":"Listar etiquetas","description":"Lista as etiquetas da organização, em ordem alfabética. Sem paginação: a lista é curta.\n\nPermissão exigida na chave: `configuracao:read`.","x-required-scope":"configuracao:read","parameters":[],"responses":{"200":{"description":"Sucesso.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: Escopo insuficiente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agente/config":{"patch":{"operationId":"updatePrimaryAgentGreeting","tags":["Agentes"],"summary":"Alterar a saudação do agente principal","description":"Troca a saudação do agente principal da organização. A alteração fica na Auditoria. Escreva a saudação como o cliente deve ouvir ou ler: no telefone ela é falada como está escrita, sem passar pela IA.\n\nPermissão exigida na chave: `agentes:edit`.","x-required-scope":"agentes:edit","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"greeting":{"type":"string","minLength":1,"description":"A nova saudação. Não pode ser vazia.","example":"Olá! Sou a assistente virtual da Exemplo Net. Como posso ajudar?"}},"required":["greeting"]}}}},"responses":{"200":{"description":"Sucesso.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","description":"Agente principal.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},"greeting":{"type":"string","description":"A saudação gravada."}},"required":["id","greeting"],"additionalProperties":false}},"required":["agent"],"additionalProperties":false}}}},"400":{"description":"`invalid_json`: O corpo da requisição não é um JSON válido. `invalid_parameter`: Parâmetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`: Escopo insuficiente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`conflict`: O estado atual do recurso não permite esta operação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"chaveDeApi":{"type":"http","scheme":"bearer","description":"Chave criada em Configurações › Integrações › Chaves de API, no formato ck_<prefixo>_<segredo>. Envie como `Authorization: Bearer ck_...`.","x-escopos":[{"valor":"conversas:read","titulo":"Leitura de conversas","explicacao":"Lê as conversas e as mensagens de todos os canais pela API, inclusive o texto que o cliente escreveu. Notas internas e conversas de teste não saem. Use para levar o atendimento ao seu BI ou CRM."},{"valor":"contatos:read","titulo":"Leitura de contatos","explicacao":"Lê os contatos e os telefones e canais de cada um pela API. São dados pessoais dos seus clientes: guarde a chave só no servidor."},{"valor":"configuracao:read","titulo":"Leitura da configuração","explicacao":"Lê a configuração da organização pela API, como a lista de etiquetas. Não altera nada."},{"valor":"agentes:edit","titulo":"Configuração do agente","explicacao":"Lê e altera a configuração do agente de IA pela API v1. Dá poder de mudar como o agente fala com o cliente. Conceda com parcimônia."}]}},"headers":{"X-Request-Id":{"description":"Identificador desta requisição. Informe ao suporte quando algo der errado.","schema":{"type":"string"}}},"schemas":{"Error":{"type":"object","description":"Corpo de toda resposta de erro.","properties":{"error":{"type":"string","description":"Frase em português para quem lê o log."},"code":{"type":"string","enum":["invalid_json","invalid_parameter","unauthenticated","invalid_credential","insufficient_scope","not_found","conflict","rate_limited","internal_error"],"description":"Código estável para comparar no seu código. A frase pode mudar; o código, não."},"retryAfter":{"type":"integer","description":"Só no 429: segundos até poder tentar de novo."}},"required":["error","code"]},"Conversation":{"type":"object","properties":{"id":{"type":"string","description":"Identificador da conversa.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},"contact_id":{"type":"string","description":"Contato com quem a conversa acontece. Leia em GET /contacts/{id}.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},"channel":{"type":"string","enum":["whatsapp","voice","instagram","messenger","telegram","email","sms","webchat","app"],"description":"Canal do atendimento: whatsapp, voice (telefone), instagram, messenger, telegram, email, sms, webchat (chat do site) ou app (app do assinante)."},"channel_id":{"anyOf":[{"type":"string","description":"Canal configurado em que a conversa entrou.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},{"type":"null"}]},"status":{"type":"string","enum":["open","pending","snoozed","resolved","closed"],"description":"open: em andamento. pending: aguardando o cliente. snoozed: adiada pela equipe. resolved: resolvida. closed: encerrada."},"protocol":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Número de protocolo mostrado ao cliente.","example":"20261109-0042"},"origin":{"type":"string","enum":["inbound","template","campaign"],"description":"inbound: o cliente iniciou. template: a equipe iniciou por modelo aprovado. campaign: veio de uma campanha."},"handled_by":{"type":"string","enum":["ai","human","hybrid"],"description":"Quem conduz a conversa agora: ai (agente de IA), human (atendente) ou hybrid."},"assigned_user_id":{"anyOf":[{"type":"string","description":"Atendente responsável, quando há.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},{"type":"null"}]},"department_id":{"anyOf":[{"type":"string","description":"Setor da conversa, quando há.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},{"type":"null"}]},"active_agent_id":{"anyOf":[{"type":"string","description":"Agente de IA que conduz a conversa, quando há.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},{"type":"null"}]},"priority":{"type":"integer","description":"Prioridade definida pela equipe. 0 é a padrão."},"tags":{"type":"array","items":{"type":"string"},"description":"Etiquetas aplicadas, pelo slug. A lista completa está em GET /tags.","example":["sem-conexao"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resumo da conversa gerado pela IA, quando já existe.","example":"Cliente sem conexão desde a manhã. A IA verificou o contrato e abriu chamado técnico."},"created_at":{"type":"string","description":"Quando a conversa começou. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"},"updated_at":{"type":"string","description":"Última alteração da conversa. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"},"last_message_at":{"type":"string","description":"Última mensagem trocada. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"},"first_response_at":{"anyOf":[{"type":"string","description":"Primeira resposta ao cliente, da IA ou de gente. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"},{"type":"null"}]},"escalated_at":{"anyOf":[{"type":"string","description":"Quando a conversa foi passada para atendimento humano. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"},{"type":"null"}]},"resolved_at":{"anyOf":[{"type":"string","description":"Quando a conversa foi resolvida. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"},{"type":"null"}]}},"required":["id","contact_id","channel","channel_id","status","protocol","origin","handled_by","assigned_user_id","department_id","active_agent_id","priority","tags","summary","created_at","updated_at","last_message_at","first_response_at","escalated_at","resolved_at"],"additionalProperties":false,"description":"Um atendimento, do primeiro contato à resolução."},"Message":{"type":"object","properties":{"id":{"type":"string","description":"Identificador da mensagem.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},"conversation_id":{"type":"string","description":"Conversa da mensagem.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},"author_type":{"type":"string","enum":["customer","ai","human_agent","system","event"],"description":"customer: o cliente. ai: o agente de IA. human_agent: um atendente. system: aviso automático do sistema. event: registro de acontecimento (por exemplo, início de ligação)."},"author_user_id":{"anyOf":[{"type":"string","description":"Atendente que escreveu, quando author_type é human_agent.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},{"type":"null"}]},"author_agent_id":{"anyOf":[{"type":"string","description":"Agente de IA que escreveu, quando author_type é ai.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},{"type":"null"}]},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Texto da mensagem. Em áudio, a transcrição; em imagem ou documento, a descrição que o sistema registrou. null em mensagem apagada."},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Legenda que o cliente escreveu junto do anexo, quando há."},"media":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","description":"Tipo do anexo: image, video, audio, audio_voicenote, document, sticker, location, contact e outros."},"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tipo MIME do arquivo.","example":"image/jpeg"},"file_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Nome do arquivo, quando informado."},"duration_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Duração em segundos, para áudio e vídeo."}},"required":["kind","mime_type","file_name","duration_sec"],"additionalProperties":false},{"type":"null"}],"description":"Anexo da mensagem, sem link para o arquivo. null quando é só texto."},"status":{"anyOf":[{"type":"string","enum":["sending","sent","delivered","read","failed"]},{"type":"null"}],"description":"Situação de entrega das mensagens enviadas ao cliente."},"reply_to_message_id":{"anyOf":[{"type":"string","description":"Mensagem respondida, quando é uma resposta.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},{"type":"null"}]},"deleted":{"type":"boolean","description":"A mensagem foi apagada. O texto não é devolvido."},"created_at":{"type":"string","description":"Quando a mensagem foi registrada. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"}},"required":["id","conversation_id","author_type","author_user_id","author_agent_id","text","caption","media","status","reply_to_message_id","deleted","created_at"],"additionalProperties":false,"description":"Uma mensagem de uma conversa. Notas internas da equipe não aparecem."},"Contact":{"type":"object","properties":{"id":{"type":"string","description":"Identificador do contato.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},"name":{"type":"string","description":"Nome do contato.","example":"Maria Souza"},"status":{"type":"string","enum":["customer","lead","former_customer","prospect","contact"],"description":"customer: cliente. lead: interessado. former_customer: ex-cliente. prospect: em prospecção. contact: só contato."},"blocked":{"type":"boolean","description":"A equipe bloqueou o contato."},"custom_fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Campos personalizados da organização."},"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["whatsapp","voice","instagram","messenger","telegram","email","sms","webchat","app"],"description":"Canal."},"identifier":{"type":"string","description":"Identificador no canal. Telefone só com dígitos, com DDI (5511987654321); nos canais sem telefone, um identificador opaco.","example":"5511987654321"},"kind":{"type":"string","enum":["phone","bsuid"],"description":"phone: é um telefone. bsuid: identificador opaco do canal."},"verified":{"type":"boolean","description":"O canal foi verificado como da pessoa."}},"required":["channel","identifier","kind","verified"],"additionalProperties":false},"description":"Canais por onde o contato fala com a organização."},"created_at":{"type":"string","description":"Quando o contato foi criado. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"},"updated_at":{"type":"string","description":"Última alteração do contato. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"}},"required":["id","name","status","blocked","custom_fields","channels","created_at","updated_at"],"additionalProperties":false,"description":"Uma pessoa com quem a organização conversa."},"Tag":{"type":"object","properties":{"id":{"type":"string","description":"Identificador da etiqueta.","example":"8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90"},"slug":{"type":"string","description":"Chave da etiqueta. É o valor que aparece em `tags` da conversa.","example":"sem-conexao"},"name":{"type":"string","description":"Nome exibido.","example":"Sem conexão"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Descrição escrita pela equipe."},"kind":{"type":"string","enum":["general","resolution"],"description":"general: etiqueta comum. resolution: marca como a conversa foi resolvida."},"created_at":{"type":"string","description":"Quando a etiqueta foi criada. Data e hora em ISO 8601, UTC.","example":"2026-11-09T14:32:05.120Z"}},"required":["id","slug","name","description","kind","created_at"],"additionalProperties":false,"description":"Etiqueta que a organização usa para classificar conversas."}}}}