Send messages

POST to the Instagram messaging endpoint with a Bearer token. The body uses the Messenger-style recipient / message shape, not the WhatsApp shape.

The basic call

Every send is a POST to ${INSTAGRAM_GRAPH_API_URL}/${INSTAGRAM_USER_ID}/messages with Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN} and a JSON body of the form { "recipient": { "id": "<igsid>" }, "message": { "text": "..." } }.

The recipient id is the Instagram-scoped sender id (IGSID) you read off the inbound webhook. For the full message-object reference see Meta's Instagram messaging docs.

curl example

curl -X POST "${INSTAGRAM_GRAPH_API_URL}/${INSTAGRAM_USER_ID}/messages" \
  -H "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "id": "17841400000000000" },
    "message": { "text": "Hello from my app" }
  }'

Node/Express example

Verbatim from the webhook starter kit (src/providers/instagram.js). It reads whichever base-URL and account-id variables your env has (sandbox sets INSTAGRAM_API_URL + INSTAGRAM_ACCOUNT_ID; your own account sets INSTAGRAM_GRAPH_API_URL + INSTAGRAM_USER_ID), so the same code runs against both.

export async function send(to, text) {
  const base = process.env.INSTAGRAM_API_URL ?? process.env.INSTAGRAM_GRAPH_API_URL;
  const accountId = process.env.INSTAGRAM_ACCOUNT_ID ?? process.env.INSTAGRAM_USER_ID;
  const url = `${base}/${accountId}/messages`;
  const res = await fetch(url, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.INSTAGRAM_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ recipient: { id: to }, message: { text } }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`Instagram API error ${res.status}: ${JSON.stringify(err)}`);
  }
  return res.json();
}

The 24-hour messaging window

You can reply within 24 hours of the user's last message.

Instagram enforces a standard messaging window. Outside the window, a plain text reply is rejected. Plan your flows to respond inside the window, or use a message tag where one applies.

Sandbox versus your own account

The sandbox proxy uses a different base URL and account-id key (INSTAGRAM_API_URL and INSTAGRAM_ACCOUNT_ID) than a real connected channel (INSTAGRAM_GRAPH_API_URL and INSTAGRAM_USER_ID). The request body shape is identical. See Sandbox for the sandbox env keys.

Next steps

• Receive Webhooks: Handle the inbound message and read the IGSID.
• Sandbox: Try the send flow end-to-end with a test account.