Visão geral da Messages API

A Messaging API permite gerenciar mensagens diretas (DM) com os interlocutores que entram em contato com seus User Profiles. Um interlocutor é a pessoa com quem seu usuário (User Profile) está se comunicando. Uma conversa é uma série de mensagens entre seu usuário (User Profile) e seu interlocutor.

• A Messaging API está incluída em todos os Ayrshare Business Plans e como um add-on pago para os planos Premium.
• Tanto para os planos Business quanto Premium, você deve ativar o Messaging na página Account do dashboard da Ayrshare.
• O Messaging está disponível para Facebook Messenger, Instagram Direct Messenger, X Direct Messages e WhatsApp (Private Beta).

​

Principais recursos de Messaging

• Gerencie as conversas dos seus usuários com os interlocutores.
• Envie mensagens de texto, imagem, vídeo e emoji em nome dos seus usuários.
• Recupere históricos completos de conversas.
• Configure respostas automáticas.
• Receba atualizações em tempo real via webhooks para mensagens recebidas, reações e confirmações de leitura.

​

Habilitar Messaging

​

Habilitar sua conta Ayrshare e User Profiles

Primeiro, você deve habilitar o Messaging para sua conta Ayrshare geral para gerenciar DMs. No dashboard da Ayrshare, vá para a página Account e clique no botão “Learn More” e, em seguida, em “Enable”. Nesse momento, você habilitou o Messaging para sua conta geral, mas ainda não ativou o Messaging para User Profiles individuais. Você pode ativar o Messaging para User Profiles individuais na página User Profiles, clicando na caixa de seleção “Messaging Active” para cada perfil, ou usando o endpoint de criação ou atualização de profiles. Após habilitar o Messaging para um User Profile, você deve vincular novamente a conta social (Facebook e Instagram) na página Social Accounts/Social Linking. Uma vez habilitado, você verá o selo “Messaging” na conta social vinculada.

​

Habilitar Messaging para WhatsApp

Vincule uma conta WhatsApp Business por meio do fluxo embedded signup da Meta, diretamente pelo dashboard da Ayrshare:

• Você precisa de uma conta Meta Business Manager, uma WhatsApp Business Account (WABA) e um número de telefone elegível. A Meta verifica a conta e o número de telefone durante o embedded signup.
• Na página Social Accounts, clique em Link no card do WhatsApp. A Ayrshare abre o pop-up de embedded signup da Meta, que orienta o cliente a selecionar/criar seu Business Manager, a WABA e o número de telefone, e a aceitar os termos da Meta.
• Quando o signup termina, a Ayrshare verifica a titularidade da WABA e do número de telefone selecionados, conclui o registro e assina a conta aos webhooks do WhatsApp. Você não digita um PIN de registro separado no dashboard da Ayrshare.

​

Comportamentos específicos importantes do WhatsApp

• Destinatários são números de telefone, não IDs. O WhatsApp identifica interlocutores por número de telefone E.164 (apenas dígitos, sem +). Os IDs de conversa retornados pela Ayrshare também são o número de telefone do interlocutor — não há IDs de conversa opacos como no Facebook e no Instagram.
• Janela de atendimento ao cliente de 24 horas. O WhatsApp Business só permite mensagens de saída em formato livre dentro de 24 horas após a mensagem mais recente do interlocutor. Fora dessa janela, a Meta rejeita o envio. Mensagens em template fora da janela de 24 horas não são suportadas atualmente pela Ayrshare.
• Envie diretamente ao destinatário pela API. Passe o número de telefone do destinatário para Send Message. A Meta só entrega uma mensagem em formato livre quando esse destinatário está dentro da janela de atendimento de 24 horas. Templates aprovados são obrigatórios para outreach a frio, e a Ayrshare não expõe atualmente o envio de templates.
• O status de entrega usa um único campo. Quando disponível em uma mensagem de saída armazenada, Get Messages retorna status como sent, delivered, read ou failed. Atualizações de status de entrega e reações do WhatsApp não são enviadas atualmente para a sua URL de webhook registrada.
• Tipos e tamanhos de mídia seguem os limites publicados pela Meta na WhatsApp Cloud API — imagens de até 5 MB, áudio e vídeo de até 16 MB e documentos de até 100 MB no momento desta publicação.

​

Mídia suportada no WhatsApp

• Imagem: .jpg, .jpeg, .png
• Vídeo: .mp4, .3gp
• Áudio: .aac, .amr, .mp3, .m4a, .ogg
• Documento: .txt, .pdf, .ppt, .pptx, .doc, .docx, .xls, .xlsx

​

Habilitar Messaging no aplicativo do Instagram

Talvez seja necessário habilitar o messaging para sua conta do Instagram:

• Vá para o seu perfil no aplicativo móvel do Instagram e toque no ícone de menu ≡ no canto superior direito para ir para a página Configurações e atividade.
• Role até a seção Como outras pessoas podem interagir com você.
• Clique em Mensagens e respostas de story.
• Toque em Solicitações de mensagem.
• Em Ferramenta conectada, ative o botão Permitir acesso a mensagens.

​

Informações importantes sobre Messaging

​

Recuperação do histórico de mensagens para Facebook e Instagram

Ao habilitar o Messaging pela primeira vez para um user profile com um Facebook ou Instagram vinculado, existem limitações importantes ao acessar o histórico de conversas:

​

Limitações da conexão inicial

• Facebook e Instagram só permitem a recuperação das últimas 20 mensagens de conversas existentes quando você vincula uma conta para messaging pela primeira vez
• Se uma conversa tiver mais de 20 mensagens, apenas as 20 mais recentes serão acessíveis inicialmente

​

Após a configuração inicial

• Uma vez que o messaging esteja habilitado, todas as novas mensagens enviadas e recebidas serão totalmente acessíveis
• A Ayrshare mantém o histórico completo de conversas a partir de então
• Por exemplo: se você inicialmente recuperar 20 mensagens e depois 100 novas mensagens forem trocadas, você poderá acessar todas as 120 mensagens no total

Esta limitação só se aplica a mensagens históricas que existiam antes de habilitar o messaging - toda a atividade futura de conversas no Facebook e no Instagram será totalmente preservada e acessível.

​

Limite de conversas e preços

• Cada Ayrshare User Profile pode ter até 1.000 conversas ativas por ciclo de cobrança. A contagem de conversas ativas é a soma de todas as redes sociais.
• Plano Premium: o Messaging é um add-on de US$ 49 por mês por conta.
• Planos Launch e Business: o Messaging é cobrado a US$ 0,09 por conversa ativa via cobrança medida do Stripe. Descontos por volume estão disponíveis; entre em contato com o seu representante de conta Ayrshare para mais detalhes.
• Uma conversa é contada como ativa para o ciclo de cobrança quando você envia uma mensagem para um destinatário. Mensagens recebidas de um destinatário não marcam, por si só, uma conversa como ativa.
• Se o limite de 1.000 conversas for atingido, você ainda poderá receber mensagens, mas não poderá responder até o início do próximo ciclo de cobrança.
• O número de mensagens, enviadas ou recebidas, em uma conversa ativa é ilimitado.
• Se precisar aumentar o limite de conversas, entre em contato com o seu representante de conta Ayrshare.

Você pode ver a contagem atual de conversas com o endpoint user.

​

Problemas de controle de messaging no Facebook e Instagram

A Meta (Facebook e Instagram) usa um sistema de “controle de thread” para conversas de messaging. Isso significa que apenas um app pode enviar mensagens em uma conversa por vez, enquanto outros apps só podem receber mensagens.

​

O que isso significa?

Se você ver o erro “Message failed to send because another app is controlling this thread now”, significa que:

• Um app de terceiros diferente controla atualmente essa conversa
• A Ayrshare só pode receber mensagens nessa conversa
• A Ayrshare não pode enviar mensagens até recuperar o controle

​

Como corrigir esse problema

Para permitir que a Ayrshare envie mensagens novamente, você precisa remover o app de terceiros que está controlando a conversa. Observe que a Meta (Facebook e Instagram) pode atualizar o processo para remover apps de terceiros, portanto, use os passos a seguir como orientação geral. Para Páginas do Facebook:

1. Acesse Facebook.com e faça login na sua conta
2. Clique no menu (☰) no canto superior direito → Configurações e privacidade → Configurações
3. Na barra lateral esquerda, clique em Apps e sites
4. Encontre o app de terceiros que está controlando o seu messaging
5. Clique em Remover ao lado desse app
6. Confirme a remoção

Para contas Business do Instagram:

1. Abra o aplicativo do Instagram no seu telefone
2. Vá para o seu Perfil → toque no menu (☰) → Configurações e privacidade
3. Toque em Apps e sites
4. Encontre e remova o app de terceiros

Alternativa para Instagram:

1. Acesse business.facebook.com
2. Navegue até Configurações do negócio
3. Em Contas, clique em Contas do Instagram
4. Selecione sua conta do Instagram
5. Verifique os apps conectados e remova aquele que está causando o problema

​

Após a remoção

Depois de remover o app de terceiros:

• O controle da thread retornará automaticamente para a Ayrshare
• Você deve conseguir enviar mensagens normalmente novamente
• Nenhuma ação adicional é necessária de sua parte

Se você continuar enfrentando problemas após remover o app, entre em contato com nossa equipe de suporte.

​

WebHooks de mensagens

Consulte Webhooks de mensagens para receber automaticamente mensagens, confirmações de leitura ou reações.