--- title: "Referência da API de mensagens" description: "Leia conversas e envie texto, anexos e templates do WhatsApp no WhatsApp, Instagram, Facebook, TikTok e no widget do site pela Public API." canonical_url: https://chatfuel.com/pt/docs/public-api/messaging markdown_url: https://chatfuel.com/pt/docs/public-api/messaging.md last_updated: 2026-10-06 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Referência da API de mensagens Leia conversas e envie texto, anexos e templates do WhatsApp no WhatsApp, Instagram, Facebook, TikTok e no widget do site pela Public API. A parte de mensagens da Public API do Chatfuel cobre a caixa de entrada: ler conversas e suas mensagens, enviar texto, arquivos e templates do WhatsApp para contatos em todos os canais, assumir um chat como humano e devolvê-lo a um flow, e escutar novas mensagens em tempo real. Tudo funciona para usuários virtuais **Agent**, então uma integração de suporte ou de CRM não precisa da função Editor. Uma conversa pertence a um contato, e o `id` dela é o mesmo valor que o ID do contato. Sempre que uma operação pedir um `conversationID`, você pode passar o ID do contato da [API de contatos](https://chatfuel.com/pt/docs/public-api/contacts). ## Como ler conversas e mensagens [#como-ler-conversas-e-mensagens] ```graphql type Bot { # Agent. The conversation with one contact. conversation(conversationID: ConversationID!): Conversation! # Agent. Number of conversations per status: open, closed, automated. conversationCount: [ConversationCountEntry!]! # Agent. Open conversations nobody has looked at yet. unseenOpenDialogsCount: Int! # Agent. The inbox list: contacts with conversations, filtered like the dashboard inbox. contactChatsConnection( first: Int!, before: ContactSearchCursor, after: ContactSearchCursor, assigneeFilter: ContactAssigneeFilter!, unreadOnly: Boolean!, salesStageV2Filter: [SalesStageV2!]!, textInputFilter: String ): ContactConnection! } ``` ```graphql query Chat($botID: BotID!, $contactID: ConversationID!) { bot(id: $botID) { conversation(conversationID: $contactID) { id platform # whatsapp, instagram, facebook, tiktok, widget status # open, closed, automated read messages(first: 20) { edges { node { id sentTime sender { name } errors { code originalErrMessage } ... on WhatsAppInTextMessage { text } ... on WhatsAppOutTextMessage { text whatsappStatus } } } pageInfo { hasNextPage endCursor } } } } } ``` `Message` é uma interface com um tipo por canal, direção e conteúdo, por exemplo `WhatsAppInTextMessage`, `InstagramInStoryReplyMessage` ou `FacebookOutAttachment`. Selecione os campos dos tipos que você trata e ignore o resto; novos tipos de mensagem podem surgir a qualquer momento. ## Como enviar mensagens [#como-enviar-mensagens] Cada canal tem uma mutação de texto e uma de anexo. Todas recebem o ID do bot e o ID da conversa (o ID do contato) e funcionam para **Agent**: ```graphql type Mutation { whatsAppTextMessageSend(botID: BotID!, conversationID: ConversationID!, message: WhatsAppTextMessageSendInput): WhatsAppOutTextMessage whatsappAttachmentMessageSend(botID: BotID!, conversationID: ConversationID!, message: WhatsAppAttachmentMessageSendInput!): WhatsAppOutAttachment instagramTextMessageSend(botID: BotID!, conversationID: ConversationID!, message: InstagramTextMessageSendInput!): InstagramOutTextMessage! instagramAttachmentMessageSend(botID: BotID!, conversationID: ConversationID!, message: InstagramAttachmentMessageSendInput!): InstagramOutAttachment facebookTextMessageSend(botID: BotID!, conversationID: ConversationID!, message: FacebookTextMessageSendInput!): FacebookOutTextMessage! facebookAttachmentMessageSend(botID: BotID!, conversationID: ConversationID!, message: FacebookAttachmentMessageSendInput!): FacebookOutAttachment tiktokTextMessageSend(botID: BotID!, conversationID: ConversationID!, message: TikTokTextMessageSendInput!): TikTokOutTextMessage! tiktokAttachmentMessageSend(botID: BotID!, conversationID: ConversationID!, message: TikTokAttachmentMessageSendInput!): TikTokOutAttachment widgetTextMessageSend(botID: BotID!, conversationID: ConversationID!, message: WidgetTextMessageSendInput): WebWidgetTextMessage widgetAttachmentMessageSend(botID: BotID!, conversationID: ConversationID!, message: WidgetAttachmentMessageSendInput): WebWidgetAttachmentMessage } ``` ```graphql mutation Reply($botID: BotID!, $contactID: ConversationID!) { whatsAppTextMessageSend( botID: $botID conversationID: $contactID message: { text: "Hi! Your order has shipped.", clientId: "order-1042-shipped" } ) { id whatsappStatus errors { code originalErrMessage } } } ``` `clientId` é um ID opcional escolhido por você; ele volta na mensagem e nos eventos de assinatura, para que você relacione seus próprios registros às mensagens do Chatfuel. Para anexos, envie o arquivo ao endpoint de upload do chat descrito em [como fazer requisições](https://chatfuel.com/pt/docs/public-api/requests) e passe o ID dele. No WhatsApp, `attachmentType` é `image`, `document` ou `audio`. As mutações de anexo podem falhar com `FileContentTypeNotSupported`, `FileTooBig` ou `FileDoesNotExist`. As regras de cada canal continuam valendo. No WhatsApp, uma mensagem livre só chega ao contato dentro da [janela de mensagens de 24 horas](https://chatfuel.com/pt/docs/whatsapp/24-hour-messaging-window) após a última mensagem do contato; depois disso, envie um template aprovado. Instagram e Facebook têm janelas de mensagens semelhantes. Problemas de entrega aparecem nos `errors` da mensagem. ## Como enviar um template do WhatsApp [#como-enviar-um-template-do-whatsapp] Enviar um template leva três passos: escolher um template aprovado, preencher os parâmetros dele e enviar o template preenchido. Todos os passos funcionam para **Agent**. ```graphql type Bot { # Agent. The bot's WhatsApp templates with their status, language, category and components. whatsAppTemplates(first: Int, after: WhatsAppTemplateCursor, before: WhatsAppTemplateCursor): WhatsappTemplates filledWhatsAppTemplate(id: FilledWhatsAppTemplateID!): FilledWhatsAppTemplate! } type Mutation { # 1. Create a one-time filled copy of a template. filledWhatsAppTemplateCreateTemporary(botID: BotID!, templateID: WhatsAppTemplateID!): FilledWhatsAppTemplate! # 2. Fill in variables and media. filledWhatsAppTemplateSetHeaderTextParamValue(templateID: FilledWhatsAppTemplateID!, name: WhatsAppTemplateTextParamName!, value: String!): FilledWhatsAppTemplate! filledWhatsAppTemplateSetBodyTextParamValue(templateID: FilledWhatsAppTemplateID!, name: WhatsAppTemplateTextParamName!, value: String!): FilledWhatsAppTemplate! filledWhatsAppTemplateSetFooterTextParamValue(templateID: FilledWhatsAppTemplateID!, name: WhatsAppTemplateTextParamName!, value: String!): FilledWhatsAppTemplate! filledWhatsAppTemplateSetHeaderImageFile(templateID: FilledWhatsAppTemplateID!, fileID: FileID!): FilledWhatsAppTemplate! filledWhatsAppTemplateSetHeaderVideoFile(templateID: FilledWhatsAppTemplateID!, fileID: FileID!): FilledWhatsAppTemplate! filledWhatsAppTemplateSetHeaderDocumentFile(templateID: FilledWhatsAppTemplateID!, fileID: FileID!, fileName: String!): FilledWhatsAppTemplate! filledWhatsAppTemplateSetURLButtonParamValue(templateID: FilledWhatsAppTemplateID!, buttonID: ComponentHandleID!, name: WhatsAppTemplateTextParamName!, value: String!): FilledWhatsAppTemplate! filledWhatsAppTemplateSetCopyCodeButtonCodeValue(templateID: FilledWhatsAppTemplateID!, buttonID: ComponentHandleID!, codeValue: String!): FilledWhatsAppTemplate! # 3. Send it to the contact. whatsAppTemplateSend(botID: BotID!, conversationID: ConversationID!, template: WhatsAppTemplateSendInput): WhatsAppOutTemplateMessage } ``` Imagens, vídeos e documentos do cabeçalho são enviados ao endpoint de upload de templates descrito em [arquivos e tarefas](https://chatfuel.com/pt/docs/public-api/files-and-tasks). Verifique `FilledWhatsAppTemplate.errors` antes de enviar: ele lista os parâmetros que ainda estão vazios ou inválidos. Use apenas templates cujo `IsSupportedInLivechat` seja `true`. [Como criar templates do WhatsApp](https://chatfuel.com/pt/docs/whatsapp/how-to-create-whatsapp-templates) explica como os templates são criados e aprovados. ## Como assumir um chat e devolvê-lo [#como-assumir-um-chat-e-devolvê-lo] ```graphql type Mutation { # Agent. Returns the conversation with a contact, creating it if the contact has none yet. conversationCreate(contactID: ContactID!): Conversation! # Agent. Opens a live chat with the contact (status open), like a teammate taking over the chat in the inbox. conversationStart(botID: BotID!, conversationID: ConversationID!): Conversation! # Agent. Closes the live chat and sends the contact to a flow. conversationFinishSendToFlow(botID: BotID!, conversationID: ConversationID!, flowID: FlowID!): Conversation! # Agent. Marks messages up to the given one as read. conversationReadMessages(botID: BotID!, conversationID: ConversationID!, before: MessageID!): Conversation! } ``` Chats ao vivo podem fechar automaticamente após um período sem mensagens. `bot.livechatAutoClosingConfig` mostra essa configuração a qualquer usuário virtual; alterá-la com `botSetLivechatAutoClosingConfig(botID, cfg: { enabled, delay })`, em que `delay` vai de `Minutes10` a `Days7`, é **Personal token only** (somente com token pessoal) e exige a função Admin. ## Assinaturas de mensagens [#assinaturas-de-mensagens] ```graphql type Subscription { # Agent. A new message in one conversation, incoming or outgoing. messageAdded(botID: BotID!, conversationID: ConversationID!): Message # Agent. A message changed, for example its WhatsApp delivery status. messageUpdated(botID: BotID!, conversationID: ConversationID!): Message # Agent. Changes in the inbox list for the given filters. contactsChatUpdates( botID: BotID!, assigneeFilter: ContactAssigneeFilter!, unreadOnly: Boolean!, salesStageV2Filter: [SalesStageV2!]!, textInputFilter: String ): ContactsChatUpdate # Agent. The number of unseen open conversations changed. unseenOpenDialogsCountChanged(botID: BotID!): Int } ``` Para acompanhar toda a caixa de entrada, assine `contactsChatUpdates` com `assigneeFilter: { type: Any }` e depois abra `messageAdded` para as conversas que interessam a você. ## Problemas comuns [#problemas-comuns] ### Uma mensagem do WhatsApp é aceita, mas nunca é entregue [#uma-mensagem-do-whatsapp-é-aceita-mas-nunca-é-entregue] Provavelmente a janela de 24 horas está fechada. Leia `errors` na mensagem retornada ou aguarde `messageUpdated`; para alcançar o contato, envie um template aprovado com `whatsAppTemplateSend`. ### "NotEnoughPermissions" ao enviar uma mensagem [#notenoughpermissions-ao-enviar-uma-mensagem] A conversa pertence a outro bot, ou as configurações de função do bot limitam o usuário virtual aos contatos atribuídos a ele. Atribua o contato ao usuário virtual com `contactSetAssignee` ou altere as configurações de função, como descrito em [equipe e funções](https://chatfuel.com/pt/docs/public-api/team-and-roles). ### "FileContentTypeNotSupported" [#filecontenttypenotsupported] O canal não aceita esse tipo de arquivo, ou o `fileType` usado no upload não corresponde a `attachmentType`. Envie o arquivo de novo com o tipo certo.