❗️
Note about identifiers
For messaging-related workflows on Instagram, use the recipient's messaging_identifier rather than the profile id.

👍
Recommendations
Incorporate realistic delays between outbound messages to mimic human behavior and reduce provider-side anti-spam triggers.

There are two common scenarios when sending Instagram messages:

You do not yet have a conversation with the recipient, so you create a new chat and send the first message with Start a Chat.
You already have a conversation, so you send a message in an existing chat with Send a Message.

Start a new conversation

Instagram conversations supported by this integration are individual conversations.

To initiate a conversation with another user, use the Start a Chat method and provide the recipient's messaging identifier.

const { data, error } = await messagingApi.startChat({
  path: {
    account_id: "acc_123456789",
  },
  body: {
    user_ids: ["17841400000000000"],
    text: "This is the first message in the chat",
  },
});

chat = messaging_api.start_chat(
    "acc_123456789",
    {
        "user_ids": ["17841400000000000"],
        "text": "This is the first message in the chat",
    },
)

📘
Note about chat ids
You may notice that the chat_id returned in the response is the same as the recipient’s messaging identifier.
This is expected behavior: for individual chats, Instagram uses the recipient’s messaging identifier as the chat identifier.

Send a message in a conversation

To send a message in an existing chat, use the Send a Message method and provide the ID of the chat to send the message in. See Retrieve chats & messages to find chat IDs.

const { data, error } = await messagingApi.sendMessage({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
  },
  body: {
    text: "Hello, world!",
  },
});

message = messaging_api.send_message(
    "chat_id",
    "acc_123456789",
    {"text": "Hello, world!"},
)

curl --request POST \
     --url https://api.unipile.com/v2/account_id/chats/chat_id/messages/send \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Hello, World!"
}
'

Send attachments

The following examples use Send a Message, but you can also send attachments with Start a Chat.

Send Images & Videos

To send an image or video with an inline preview, call the Send a Message method and include files in the attachments array.

Any file with a MIME type starting with image/ or video/ will be sent as media with an inline preview in the chat.

const imageFile = await readFile("image.png");
const videoFile = await readFile("video.mp4");

const { data, error } = await messagingApi.sendMessage({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
  },
  body: {
    text: "",
    attachments: [
      {
        content: imageFile.toString("base64"),
        content_type: "image/png",
        filename: "image.png",
      },
      {
        content: videoFile.toString("base64"),
        content_type: "video/mp4",
        filename: "video.mp4",
      },
    ],
  },
});

import base64

with open("image.png", "rb") as f:
    image_file = base64.b64encode(f.read()).decode("utf-8")
with open("video.mp4", "rb") as f:
    video_file = base64.b64encode(f.read()).decode("utf-8")

message = messaging_api.send_message(
    "chat_id",
    "acc_123456789",
    {
        "text": "",
        "attachments": [
            {
                "content": image_file,
                "content_type": "image/png",
                "filename": "image.png",
            },
            {
                "content": video_file,
                "content_type": "video/mp4",
                "filename": "video.mp4",
            },
        ],
    },
)

curl --request POST \
     --url https://api.unipile.com/v2/account_id/chats/chat_id/messages/send \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "attachments": [
    {
      "content": "base64",
      "content_type": "image/png",
      "filename": "image.png",
    },
    {
      "content": "base64",
      "content_type": "video/mp4",
      "filename": "video.mp4",
    }

  ]
}
'

Reply to a specific message

To send a message as a reply to a specific message (to see the replied message embedded), use the Send a Message method and provide the ID of the message to reply to as quote_id.

const { data, error } = await messagingApi.sendMessage({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
  },
  body: {
    text: "This is a reply to a message",
    quote_id: "message_id",
  },
});

message = messaging_api.send_message(
    "chat_id",
    "acc_123456789",
    {
        "text": "This is a reply to a message",
        "quote_id": "message_id",
    },
)

curl --request POST \
     --url https://api.unipile.com/v2/account_id/chats/chat_id/messages/send \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "quote_id": "message_id",
  "text": "This is a reply to a message"
}
'

Edit a sent message

To edit a sent message, use Modify a Message.

Instagram allows the account owner to edit a sent message for up to 15 minutes after it was sent.

const { data, error } = await messagingApi.modifyMessage({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
    message_id: "message_id",
  },
  body: {
    text: "Updated message text",
  },
});

messaging_api.modify_message(
    "chat_id",
    "message_id",
    "acc_123456789",
    {"text": "Updated message text"},
)

curl --request POST \
     --url https://api.unipile.com/v2/account_id/chats/chat_id/messages/message_id/modify \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Updated message text"
}
'

📘
Message editing is only available within 15 minutes after the original send time.

Forward a message to another chat

To forward a message to another chat, use Forward a Message and provide the destination chat ID in the request body.

const { data, error } = await messagingApi.forwardMessage({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
    message_id: "message_id",
  },
  body: {
    chat_id: "destination_chat_id",
  },
});

messaging_api.forward_message(
    "chat_id",
    "message_id",
    "acc_123456789",
    {"chat_id": "destination_chat_id"},
)

curl --request POST \
     --url https://api.unipile.com/v2/account_id/chats/chat_id/messages/message_id/forward \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "chat_id": "destination_chat_id"
}
'