Instagram Voice Notes

Overview

Svara sends native voice messages on Instagram Direct through the Instagram Graph API. Voice notes appear as playable audio messages in the recipient's DM thread, the same as recording a voice message directly in the Instagram app.

Your Instagram Professional Account (Business or Creator) acts as the sender. Messages can only be sent to users who have an existing conversation with your account, and must be sent within a 24-hour messaging window after the user's last message to you.

Required session data

| Field | Type | Description | |---|---|---| | access_token | string | A valid Instagram Graph API access token with instagram_manage_messages permission | | ig_user_id | string | Your Instagram Professional Account's user ID |

How to get credentials

1. Set up an Instagram Professional Account

1. Convert your Instagram account to a Business or Creator account in Instagram settings.
2. Connect it to a Facebook Page.

2. Create a Meta App

1. Go to developers.facebook.com and create a new app.
2. Select Business as the app type.
3. Add the Instagram product to your app.

3. Generate an access token

1. In your Meta App dashboard, navigate to Instagram > Basic Display or use the Graph API Explorer.
2. Request the instagram_manage_messages permission.
3. Generate a User Access Token.
4. For production, exchange it for a long-lived token (valid for 60 days, renewable).

export INSTAGRAM_ACCESS_TOKEN="IGQVJWZAm..."
export INSTAGRAM_USER_ID="17841400123456789"

4. Get the recipient's Instagram-scoped ID

The recipient is identified by their Instagram-Scoped User ID (IGSID) — a unique identifier you receive when a user messages your Professional Account. You get IGSIDs through the Instagram Messaging webhook or the Conversations API.

The 24-hour messaging window

Instagram enforces a strict 24-hour messaging window:

• You can only send messages within 24 hours of the user's last message to your account.
• After 24 hours, you cannot send messages until the user messages you again.
• This applies to all message types, including voice notes.

Plan your voice note sends accordingly. If you need to send outside the window, consider using a Message Tag (if eligible) or prompting the user to re-engage first.

Audio format

Instagram voice messages use M4A (AAC) format. Svara handles conversion automatically:

| Input format | Behavior | |---|---| | M4A / AAC | Sent directly, no conversion needed | | MP3 | Auto-converted to M4A/AAC | | OGG / OPUS | Auto-converted to M4A/AAC | | WAV | Auto-converted to M4A/AAC | | WebM | Auto-converted to M4A/AAC |

Audio files must be under 25 MB. Voice messages are limited to 60 seconds on Instagram.

Example request

curl -X POST https://api.svarapi.io/v1/send \
  -H "Authorization: Bearer $SVARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "recipient": "7249103847561234",
    "audio_url": "https://cdn.example.com/notes/update.m4a",
    "session": {
      "access_token": "IGQVJWZAm...",
      "ig_user_id": "17841400123456789"
    }
  }'

const response = await fetch("https://api.svarapi.io/v1/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SVARA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: "instagram",
    recipient: "7249103847561234",
    audio_url: "https://cdn.example.com/notes/update.m4a",
    session: {
      access_token: process.env.INSTAGRAM_ACCESS_TOKEN,
      ig_user_id: process.env.INSTAGRAM_USER_ID,
    },
  }),
});

const result = await response.json();
console.log(`Voice note queued: ${result.id}`);

import requests

response = requests.post(
    "https://api.svarapi.io/v1/send",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "platform": "instagram",
        "recipient": "7249103847561234",
        "audio_url": "https://cdn.example.com/notes/update.m4a",
        "session": {
            "access_token": access_token,
            "ig_user_id": ig_user_id,
        },
    },
)

result = response.json()
print(f"Voice note queued: {result['id']}")

Common errors

| Error | Cause | Solution | |---|---|---| | invalid_token | The access token is expired or malformed | Generate a new token or refresh your long-lived token | | invalid_ig_user_id | The Instagram user ID does not match the access token | Verify your ig_user_id matches the authenticated account | | recipient_not_found | The IGSID is invalid or the user has no conversation with your account | The user must message your account first | | messaging_window_closed | More than 24 hours since the user's last message | Wait for the user to message you again before sending | | audio_too_large | The audio file exceeds 25 MB | Compress or shorten your audio | | audio_too_long | The audio exceeds 60 seconds | Trim your audio to under 60 seconds | | audio_fetch_failed | Could not download the audio from the URL | Ensure the URL is publicly accessible |