Quick Start

Del cero al primer DM en cola en pocos pasos. Elige oficial (Meta) o no oficial. Las mismas rutas de envío sirven para ambos.

En pocas palabras

Oficial: login Meta en el panel o enlace compartible; destinatario = IGSID; ventana de 24h
No oficial: usuario y contraseña (o enlace); acceptInstagramTerms: true; warm-up en cuenta nueva
En ambos casos usas la misma API; solo cambia cómo conectas la cuenta

¿Dudas sobre cuál elegir? Ve Modos de conexión.

Antes de empezar

Una clave de API (sk_live_... o sk_test_... para sandbox)
Permisos de instancia y envío en la clave. Ve Alcances
En los ejemplos, reemplaza sk_live_xxxxx por tu clave

¿Empezando ahora? Usa sk_test_... y comprueba el resultado en la Bandeja sandbox.

Conexión oficial
Conexión no oficial

1. Conectar la cuenta

Tres caminos, elige el que encaje con tu integración:

1A, Por el panel

Instagram → Nueva conexión → Oficial
Inicia sesión con Meta (o pega credenciales manuales en el draft)
Cuando el estado quede activo, anota el id de la instancia

1B, Por API con enlace para el cliente

POST /v1/instagram/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Atendimento IG",
  "mode": "OFFICIAL",
  "generateShareableLink": true
}

Respuesta esperada: 200 con instancia PENDING y el enlace:

{
  "success": true,
  "data": {
    "instance": {
      "id": "clxx123...",
      "name": "Atendimento IG",
      "status": "PENDING",
      "mode": "OFFICIAL"
    },
    "shareableLink": {
      "hostedUrl": "https://api.notifique.dev/w/instance-connect/...?token=...",
      "embedUrl": "https://api.notifique.dev/w/embed/instance-connect/...?token=..."
    }
  }
}

Envía shareableLink.hostedUrl al cliente. En la página ve Continuar con Meta. Al terminar, la instancia queda ACTIVE.

Quien tenga el enlace puede conectar o desconectar la instancia. Después del uso, rota el secret si está disponible en la API de connect-page.

1C, Por API con credenciales Meta

Embedded (tras Facebook Login en el navegador):

{
  "name": "Atendimento IG",
  "mode": "OFFICIAL",
  "metaEmbeddedCode": "CODE_DO_EMBEDDED_SIGNUP"
}

BYOK (token e IDs que ya tienes):

{
  "name": "Atendimento IG",
  "mode": "OFFICIAL_BYOK",
  "metaAccessToken": "EAAxx...",
  "facebookPageId": "123456789012345",
  "igBusinessAccountId": "17841400000000000",
  "metaAppSecret": "abc123..."
}

2. Cómo obtener el IGSID del destinatario

En modo oficial, el campo to usa el IGSID (ID scoped de la Page), no @username.

Webhook instagram.received: campo from en el mensaje entrante
API GET /v1/instagram/messages/inbound/{id} tras el DM del cliente
Panel: detalle del mensaje recibido

3. Enviar el primer DM

POST /v1/instagram/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "instanceId": "clxx123...",
  "to": ["17841400000000000"],
  "type": "text",
  "payload": { "message": "Olá! Como posso ajudar?" }
}

Respuesta esperada: 202 con el mensaje en cola:

{
  "success": true,
  "data": {
    "messageIds": ["msg_abc..."],
    "status": "QUEUED",
    "count": 1
  }
}

En oficial, la conversación debe estar en la ventana de 24h tras el último mensaje del cliente.

4. Después del primer envío

Configura el webhook Meta en {tu_base}/webhooks/meta/instagram, escucha instagram.received y el estado de envío. Para hide de comentarios, usa las rutas de comments en la referencia de la API.

1. Conectar la cuenta

1A, Por el panel

Instagram → Nueva conexión → No oficial
Usuario y contraseña (y 2FA si lo pide)
Acepta los términos; espera estado activo

1B, Por API con credenciales

POST /v1/instagram/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Atendimento IG",
  "mode": "UNOFFICIAL",
  "acceptInstagramTerms": true,
  "auth": {
    "mode": "password",
    "username": "sua_conta",
    "password": "sua_senha"
  }
}

Si Meta pide verificación, envía verificationCode en el create o usa POST /v1/instagram/instances/{id}/challenge/resolve.

1C, Por API con enlace compartible

{
  "name": "Atendimento IG",
  "mode": "UNOFFICIAL",
  "acceptInstagramTerms": true,
  "generateShareableLink": true
}

Respuesta: connection.status = pending_login + shareableLink. El cliente abre el enlace e introduce usuario/contraseña.

Cuenta nueva: lee la política anti-suspensión (warm-up, cooldown).

2. Enviar el primer DM

{
  "instanceId": "clxx123...",
  "to": ["nome_do_usuario"],
  "type": "text",
  "payload": { "message": "Olá!" }
}

Respuesta esperada: 202 (mismo formato que la pestaña oficial).

3. Después del primer envío

Configura webhooks del workspace. En no oficial puedes editar y unsend DMs enviados.

Todos los tipos de envío

En la referencia de la API, abre Enviar mensaje en Instagram (POST /v1/instagram/messages) y elige el ejemplo en el playground: Texto, Imagen, Vídeo, Audio, Documento, Programado, IGSID oficial o username no oficial.

API Instagram

En pocas palabras

Antes de empezar

1. Conectar la cuenta

1A, Por el panel

1B, Por API con enlace para el cliente

1C, Por API con credenciales Meta

2. Cómo obtener el IGSID del destinatario

3. Enviar el primer DM

4. Después del primer envío

1. Conectar la cuenta

1A, Por el panel

1B, Por API con credenciales

1C, Por API con enlace compartible

2. Enviar el primer DM

3. Después del primer envío

Todos los tipos de envío

Próximos pasos

​En pocas palabras

​Antes de empezar

​1. Conectar la cuenta

​1A, Por el panel

​1B, Por API con enlace para el cliente

​1C, Por API con credenciales Meta

​2. Cómo obtener el IGSID del destinatario

​3. Enviar el primer DM

​4. Después del primer envío

​1. Conectar la cuenta

​1A, Por el panel

​1B, Por API con credenciales

​1C, Por API con enlace compartible

​2. Enviar el primer DM

​3. Después del primer envío

​Todos los tipos de envío

​Próximos pasos

En pocas palabras

Antes de empezar

1. Conectar la cuenta

1A, Por el panel

1B, Por API con enlace para el cliente

1C, Por API con credenciales Meta

2. Cómo obtener el IGSID del destinatario

3. Enviar el primer DM

4. Después del primer envío

1. Conectar la cuenta

1A, Por el panel

1B, Por API con credenciales

1C, Por API con enlace compartible

2. Enviar el primer DM

3. Después del primer envío

Todos los tipos de envío

Próximos pasos