Send messages

Learn how to send, edit, forward, and delete messages on Facebook using Unipile API.

👍

Recommendations

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

📘

A successful response does not prove delivery

A 200 response means that the message was accepted, not that Facebook delivered it. To confirm delivery, wait for the matching message.new webhook event.


Start a new conversation

To start a conversation, use Start a Chat and pass the ID of a person or a Page in users_ids.

const { data } = await messagingApi.startChat({
  path: {
    account_id: "acc_123456789",
  },
  body: {
    users_ids: "100001234567890",
    text: "This is the first message in the chat",
  },
});
chat = messaging_api.start_chat(
    "acc_123456789",
    {
        "users_ids": "100001234567890",
        "text": "This is the first message in the chat",
    },
)
curl --request POST \
     --url https://api.unipile.com/v2/acc_123456789/chats/send \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "users_ids": "100001234567890",
  "text": "This is the first message in the chat"
}
'

If Facebook does not allow the account to message this person, the request fails with provider/access_restricted.

A Facebook Page can't start a conversation: it can only reply in its existing chats.


Send a message in a conversation

To send a message in an existing chat, use Send a Message. See Retrieve chats & messages to find chat IDs. Use the PAGE_<page_id>_<thread_key> ID of a chat to reply as a Page.

const { data } = 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/acc_123456789/chats/chat_id/messages/send \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Hello, world!"
}
'

Send attachments

To send files, include them in the attachments array of Send a Message. For large files, prefer multipart.

On encrypted chats, each file is sent as a separate message, and the response gives the ID of the last one.

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

const { data } = 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",
      },
    ],
  },
});
import base64

with open("image.png", "rb") as f:
    image_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",
            },
        ],
    },
)
curl --request POST \
     --url https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/send \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "",
  "attachments": [
    {
      "content": "base64",
      "content_type": "image/png",
      "filename": "image.png"
    }
  ]
}
'

Edit a message

To edit a message, use Modify a Message.

const { data } = await messagingApi.modifyMessage({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
    message_id: "message_id",
  },
  body: {
    text: "Updated message text",
  },
});
message = messaging_api.modify_message(
    "chat_id",
    "message_id",
    "acc_123456789",
    {"text": "Updated message text"},
)
curl --request POST \
     --url https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/modify \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Updated message text"
}
'

Forward a message

To forward a message, use Forward a Message and provide the destination chat in chat_id.

Forwarding a message with attachments or without text from an unencrypted chat to an encrypted one returns 501 api/not_implemented.

const { data } = await messagingApi.forwardMessage({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
    message_id: "message_id",
  },
  body: {
    chat_id: "destination_chat_id",
  },
});
message = messaging_api.forward_message(
    "chat_id",
    "message_id",
    "acc_123456789",
    {"chat_id": "destination_chat_id"},
)
curl --request POST \
     --url https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id/forward \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "chat_id": "destination_chat_id"
}
'

Delete a message

To delete a message, use Delete a Message. A Facebook Page can't delete its messages.

await messagingApi.deleteMessage({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
    message_id: "message_id",
  },
});
messaging_api.delete_message(
    "chat_id",
    "message_id",
    "acc_123456789",
)
curl --request DELETE \
     --url https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages/message_id \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json'

Be notified about edited and deleted messages

To be notified, set up a Webhook that listens for message.update and message.delete events.


Did this page help you?