Quick Start

From zero to the first queued DM in a few steps. Choose official (Meta) or unofficial. The same send routes serve both.

In short

Official: Meta login in the panel or shareable link; recipient = IGSID; 24h window
Unofficial: username and password (or link); acceptInstagramTerms: true; warm-up on new accounts
In both cases you use the same API; only how you connect the account changes

Not sure which to pick? See Connection modes.

Before you start

An API key (sk_live_... or sk_test_... for sandbox)
Instance and send permissions on the key. See Scopes
In the examples, replace sk_live_xxxxx with your key

Just getting started? Use sk_test_... and check the result in the Sandbox inbox.

Official connection
Unofficial connection

1. Connect the account

Three paths, pick what fits your integration:

1A, Via dashboard

Instagram → New connection → Official
Sign in with Meta (or paste manual credentials on the draft)
When status is active, note the instance id

1B, API with a client link

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

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

Expected response: 200 with PENDING instance and the link:

{
  "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=..."
    }
  }
}

Send shareableLink.hostedUrl to the client. On the page they see Continue with Meta. When done, the instance becomes ACTIVE.

Anyone with the link can connect or disconnect the instance. After use, rotate the secret if available in the connect-page API.

1C, API with Meta credentials

Embedded (after Facebook Login in the browser):

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

BYOK (token and IDs you already have):

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

2. How to get the recipient’s IGSID

In official mode, the to field uses IGSID (Page-scoped ID), not @username.

Webhook instagram.received: from field on the inbound message
API GET /v1/instagram/messages/inbound/{id} after the customer sends a DM
Dashboard: received message detail

3. Send the first 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?" }
}

Expected response: 202 with the message queued:

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

On official, the conversation must be within the 24h window after the customer’s last message.

4. After the first send

Configure the Meta webhook at {your_base}/webhooks/meta/instagram, listen for instagram.received and send status. For comment hide, use the comments routes in the API reference.

1. Connect the account

1A, Via dashboard

Instagram → New connection → Unofficial
Enter username and password (and 2FA if asked)
Accept the terms; wait for active status

1B, API with credentials

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"
  }
}

If Meta asks for verification, send verificationCode on create or use POST /v1/instagram/instances/{id}/challenge/resolve.

1C, API with a shareable link

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

Response: connection.status = pending_login + shareableLink. The client opens the link and enters username/password.

New account: read the anti-suspension policy (warm-up, cooldown).

2. Send the first DM

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

Expected response: 202 (same format as the official tab).

3. After the first send

Configure workspace webhooks. On unofficial you can edit and unsend sent DMs.

All send types

In the API reference, open Send Instagram message (POST /v1/instagram/messages) and pick the example in the playground: Text, Image, Video, Audio, Document, Scheduled, official IGSID, or unofficial username.

Instagram API

In short

Before you start

1. Connect the account

1A, Via dashboard

1B, API with a client link

1C, API with Meta credentials

2. How to get the recipient’s IGSID

3. Send the first DM

4. After the first send

1. Connect the account

1A, Via dashboard

1B, API with credentials

1C, API with a shareable link

2. Send the first DM

3. After the first send

All send types

Next steps

​In short

​Before you start

​1. Connect the account

​1A, Via dashboard

​1B, API with a client link

​1C, API with Meta credentials

​2. How to get the recipient’s IGSID

​3. Send the first DM

​4. After the first send

​1. Connect the account

​1A, Via dashboard

​1B, API with credentials

​1C, API with a shareable link

​2. Send the first DM

​3. After the first send

​All send types

​Next steps

In short

Before you start

1. Connect the account

1A, Via dashboard

1B, API with a client link

1C, API with Meta credentials

2. How to get the recipient’s IGSID

3. Send the first DM

4. After the first send

1. Connect the account

1A, Via dashboard

1B, API with credentials

1C, API with a shareable link

2. Send the first DM

3. After the first send

All send types

Next steps