Instagram

O id do caminho#

Em POST /{version}/{id}/messages, {id} é o ig-user-id da conta (só dígitos, de 1 a 32). A {version} segue o formato de sempre (v25.0) e não muda o comportamento.

A chave syn_… carrega só a organização, então a Synergy descobre o canal pelo id:

1. Um número de WhatsApp da organização que ela já resolveu vai pelo caminho do WhatsApp, como sempre.
2. Uma conta do Instagram que já respondeu antes vai direto para a conta.
3. Um id novo é tentado como conta do Instagram uma vez. Se a conta não existe, ou é de outra organização, a resposta é igual à de um id que não existe (404, código 100): ninguém descobre de quem é uma conta.

O terceiro passo tem um limite por chave: 30 ids novos por minuto, por servidor. Passando disso, a Synergy pula a tentativa e segue o caminho do WhatsApp. Se o id for um número seu, o envio acontece normalmente. Se não for, a resposta é 429 com Retry-After: 1, nunca um 404: sem a tentativa, a Synergy não sabe dizer que o id não existe. Repita depois de 1 segundo.

Uma chave restrita a alguns números e contas (instanceIds) só alcança esses: numa conta fora da restrição ela responde 401 (código 190), como num número de WhatsApp fora dela. Uma conta de outra organização responde 404.

Enviar uma mensagem direta#

O corpo é estrito: um campo desconhecido é recusado com 400 (código 100). Escolha um destinatário e uma mensagem.

Toda URL (attachment.payload.url, web_url dos botões) precisa ser https:, sem usuário e senha. O corpo inteiro tem até 64 KB.

A resposta, quando a Meta aceita, tem o formato dela:

Mais exemplos de corpo:

Idempotência#

Idempotency-Key funciona como no WhatsApp (Enviar mensagens): repetir a requisição com a mesma chave responde o mesmo message_id e a mensagem sai uma vez só. Enquanto o primeiro envio está em andamento, a repetição recebe 409 (código 1390002); reusar a chave para outra pessoa recebe 422 (código 1390003).

De quem é a conversa depois do envio#

Como no WhatsApp, a conversa passa para a automação (status automated, dona: a chave). Com uma chave notify, a resposta da pessoa vai para a fila dos atendentes; com bot, continua com a integração. Uma chave bot não envia para uma conversa que está com um atendente (409, código 1390001).

curl -X POST 'https://api.synergyconnect.com.br/v25.0/17841400000000001/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-42-saiu' \
  -d '{"recipient":{"id":"17841400000000099"},"message":{"text":"Seu pedido saiu para entrega!"}}'

const res = await fetch('https://api.synergyconnect.com.br/v25.0/17841400000000001/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-42-saiu',
  },
  body: JSON.stringify({
    recipient: { id: '17841400000000099' },
    message: { text: 'Seu pedido saiu para entrega!' },
  }),
});
const { recipient_id, message_id } = await res.json();

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/17841400000000001/messages",
    headers={
        "Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
        "Idempotency-Key": "pedido-42-saiu",
    },
    json={
        "recipient": {"id": "17841400000000099"},
        "message": {"text": "Seu pedido saiu para entrega!"},
    },
)
data = res.json()  # {"recipient_id": "...", "message_id": "..."}

{
  "recipient_id": "17841400000000099",
  "message_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDAw"
}

{
  "recipient": { "id": "17841400000000099" },
  "message": {
    "text": "Quer ver o catálogo?",
    "quick_replies": [
      { "content_type": "text", "title": "Sim", "payload": "catalogo.sim" },
      { "content_type": "text", "title": "Agora não", "payload": "catalogo.nao" }
    ]
  }
}

{
  "recipient": { "id": "17841400000000099" },
  "message": {
    "attachment": {
      "type": "image",
      "payload": { "url": "https://cdn.exemplo.com.br/promocao.jpg" }
    }
  }
}

{
  "recipient": { "id": "17841400000000099" },
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "button",
        "text": "Acompanhe o seu pedido:",
        "buttons": [{ "type": "web_url", "title": "Rastrear", "url": "https://loja.exemplo.com.br/pedidos/42" }]
      }
    }
  }
}

{ "recipient": { "id": "17841400000000099" }, "sender_action": "typing_on" }

A janela de 24 horas#

A conta só envia mensagem livre dentro de 24 horas da última mensagem da pessoa. Diferente do WhatsApp, a Synergy confere a janela antes de chamar a Meta: fora dela a resposta é imediata e nenhuma mensagem é enviada. A API nunca usa a etiqueta Human Agent (a janela estendida de 7 dias da Meta), que fica reservada aos atendentes na plataforma. Veja Janela de atendimento de 24 horas.

Limites#

Os limites do Instagram estão em Limites de taxa: a borda por chave e conta, a vazão da conta, a fila de respostas privadas e o teto de envelopes por endpoint.