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.
Última atualização
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.
Como ler conversas e mensagens
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!
}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
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:
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
}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 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 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
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.
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. 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 explica como os templates são criados e aprovados.
Como assumir um chat e devolvê-lo
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
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
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
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.
"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.
Referência da API de contatos
Pesquise, leia e atualize contatos do Chatfuel: atributos, nomes, notas, responsáveis e etapas de vendas, segmentos, importação e exportação CSV e eventos.
Referência da API de flows
Leia e crie flows do Chatfuel pela Public API: flows e grupos, blocos e conexões, componentes de mensagem e ação, regras de palavras-chave e Test chat.