Seguir para receber

Na API, é uma regra de comentário com tipo: "seguir", criada por POST /regras-comentario. Precisa dos escopos automacoes:ler e automacoes:escrever, do módulo Automações no plano e do recurso liberado na organização (é o mesmo dos botões; sem ele, 403 recurso_desligado).

Como funciona#

• Cada pessoa recebe o conteúdo uma vez só, mesmo que comente de novo.
• Quem já seguia recebe texto_ja_segue e o conteúdo. Quem seguiu depois do pedido recebe texto_seguiu_depois e o conteúdo.
• O botão "Estou seguindo" pode ser tocado quantas vezes for preciso, até max_tentativas. Quando as tentativas acabam, vai texto_limite (se você definiu) e a FORSI para de responder a essa pessoa.

Passo a passo#

1. Pegue a conta. GET /instagram/contas lista as contas conectadas. O id de cada uma é o conexao_id da regra.
2. Escolha o post. Mande o post_id da publicação. Sem ele (null), a regra vale para todos os posts da conta.
3. Crie a regra com tipo: "seguir", as palavras-chave, resposta_privada (a mensagem que leva o botão, até 640 caracteres) e seguir.conteudo.texto. O resto do bloco seguir é opcional e tem padrão. Mande ativo: true para a regra já nascer ligada.
4. Teste comentando a palavra-chave no post com um perfil que não segue a conta, e depois com um que segue.
5. Acompanhe em GET /regras-comentario/{id}: estatisticas traz pediram (receberam o botão), entregues (receberam o conteúdo), ja_seguiam, seguiram_depois e aguardando.

Requisição completa#

Só o mínimo; o resto do bloco seguir usa os padrões da tabela abaixo:

curl -X POST "https://chat.forsi.com.br/api/v1/regras-comentario" \
  -H "Authorization: Bearer $FORSI_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{
    "nome": "Guia grátis",
    "conexao_id": "54b27747-86c2-455a-91a4-c0c02d0bd891",
    "post_id": "17912345678901234",
    "palavras": ["guia"],
    "responder_publico": "Te chamei no direct!",
    "resposta_privada": "Oi, {nome}! Toque no botão para receber o guia.",
    "tipo": "seguir",
    "seguir": {"conteudo":{"texto":"Aqui está o seu guia!"}},
    "ativo": true
  }'

const resposta = await fetch('https://chat.forsi.com.br/api/v1/regras-comentario', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FORSI_CHAVE}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-4821',
  },
  body: JSON.stringify({
    "nome": "Guia grátis",
    "conexao_id": "54b27747-86c2-455a-91a4-c0c02d0bd891",
    "post_id": "17912345678901234",
    "palavras": ["guia"],
    "responder_publico": "Te chamei no direct!",
    "resposta_privada": "Oi, {nome}! Toque no botão para receber o guia.",
    "tipo": "seguir",
    "seguir": {"conteudo":{"texto":"Aqui está o seu guia!"}},
    "ativo": true
  }),
});
const json = await resposta.json();
if (!resposta.ok) throw new Error(`${resposta.status} ${json.erro.codigo}: ${json.erro.mensagem}`);
console.log(json.dados);

import os
import requests

resposta = requests.post(
    "https://chat.forsi.com.br/api/v1/regras-comentario",
    headers={
        "Authorization": f"Bearer {os.environ['FORSI_CHAVE']}",
        "Idempotency-Key": "pedido-4821",
    },
    json={
        "nome": "Guia grátis",
        "conexao_id": "54b27747-86c2-455a-91a4-c0c02d0bd891",
        "post_id": "17912345678901234",
        "palavras": ["guia"],
        "responder_publico": "Te chamei no direct!",
        "resposta_privada": "Oi, {nome}! Toque no botão para receber o guia.",
        "tipo": "seguir",
        "seguir": {
            "conteudo": {
                "texto": "Aqui está o seu guia!",
            },
        },
        "ativo": True,
    },
    timeout=30,
)
corpo = resposta.json()
if not resposta.ok:
    raise RuntimeError(f"{resposta.status_code} {corpo['erro']['codigo']}: {corpo['erro']['mensagem']}")
print(corpo["dados"])

A resposta é 201 com a regra criada e o bloco seguir completo, já com os padrões. O mesmo pedido com todos os campos:

{
  "nome": "Guia grátis",
  "conexao_id": "54b27747-86c2-455a-91a4-c0c02d0bd891",
  "post_id": "17912345678901234",
  "palavras": ["guia"],
  "responder_publico": "Te chamei no direct!",
  "resposta_privada": "Oi, {nome}! Toque no botão para receber o guia.",
  "tipo": "seguir",
  "seguir": {
    "botao_receber": "Quero receber",
    "texto_nao_segue": "Para receber, é só seguir o perfil @{conta} e depois tocar em \"Estou seguindo\".",
    "botao_estou_seguindo": "Estou seguindo",
    "texto_ainda_nao_segue": "Ainda não apareceu que você segue @{conta}. Siga o perfil e toque de novo em \"Estou seguindo\".",
    "texto_ja_segue": "Que bom ter você por aqui! Aqui está o que você pediu:",
    "texto_seguiu_depois": "Obrigado por seguir! Aqui está o que você pediu:",
    "conteudo": {
      "texto": "Seu guia completo está aqui.",
      "botao": {"titulo":"Abrir o guia","url":"https://exemplo.com.br/guia"}
    },
    "max_tentativas": 5,
    "texto_limite": "Quando seguir, é só comentar de novo.",
    "se_nao_verificar": "enviar"
  },
  "ativo": true
}

Nesse tipo não use automacao_id nem botoes: o botão vem de seguir.botao_receber. A resposta pública (responder_publico), as variações e esconder o comentário funcionam normalmente.

Campos do bloco seguir#

Os textos aceitam {nome}, {usuario} e {conta}: o nome e o @ de quem comentou e o @ da sua conta. Os dois botões não trocam variáveis. Cada texto vai até 900 bytes (emoji e acento contam mais que uma letra), porque a mensagem direta do Instagram vai até 1000 bytes.

Editar uma regra#

No PATCH /regras-comentario/{id}, sem tipo a regra mantém o tipo. Em seguir, só os campos enviados mudam: os que você omitir mantêm o valor atual, inclusive dentro de conteudo (mande só texto ou só botao; botao: null tira o botão). max_tentativas: null e texto_limite: null voltam ao padrão. tipo: "comum" apaga o bloco seguir. Ao trocar uma regra comum para seguir, o que faltar vem dos padrões e conteudo.texto é obrigatório.

{
  "seguir": {"conteudo":{"texto":"Novo texto do conteúdo."},"max_tentativas":3}
}

{"tipo":"comum"}

Respostas#

Toda regra traz tipo. Nas regras seguir, o bloco seguir vem completo, com os padrões. Campo sem valor não aparece: conteudo.botao, max_tentativas e texto_limite somem enquanto forem null, e seguir some na regra comum. GET /regras-comentario/{id} e a listagem trazem estatisticas. Filtre a listagem com ?tipo=seguir.

Erros#

• 403 recurso_desligado: o Seguir para receber não está liberado na organização (é o mesmo recurso dos botões).
• 422 seguir_invalido: um campo de seguir está vazio, passa do limite, tem { num dos dois botões, tem caractere de controle ou invisível, ou passa de 900 bytes. A mensagem diz qual campo.
• 422 limite_de_regras: a organização já tem 200 regras.

Perguntas frequentes#

A FORSI confere mesmo se a pessoa segue?#

Sim, a cada toque no botão. Se o Instagram não deixar conferir, vale se_nao_verificar: enviar (padrão) entrega o conteúdo assim mesmo e pedir_de_novo pede para seguir outra vez.

Quem comentar duas vezes recebe duas vezes?#

Não. Cada pessoa recebe o conteúdo uma vez só.

Posso usar variáveis nos botões?#

Não. botao_receber e botao_estou_seguindo não trocam variáveis, e um { neles dá 422 seguir_invalido. Nos textos, use {nome}, {usuario} e {conta}.

Dá para transformar uma regra comum em Seguir para receber?#

Dá, com PATCH e tipo: "seguir". O que faltar vem dos padrões, mas seguir.conteudo.texto é obrigatório. Para voltar, mande tipo: "comum": o bloco seguir é apagado.

O que acontece se eu não mandar post_id?#

A regra vale para todos os posts da conta e responde a palavra-chave em qualquer publicação. Se o conteúdo é de um post só, mande sempre o post_id.

O que a pessoa vê se nunca seguir?#

A cada toque em "Estou seguindo" ela recebe texto_ainda_nao_segue. Com max_tentativas, quando as tentativas acabam vai texto_limite (se houver) e a FORSI para de responder a ela. Sem max_tentativas, a FORSI confere até 50 vezes.