Get individual and group chats

All chats are grouped into a single inbox. To fetch them, use the List all Chats method.
You can apply filters such as archive status, unread status, or chat type (individual or group).

const { data, error } = await messagingApi.getChatsList({
  path: {
    account_id: "acc_123456789",
  },
  query: {
    limit: 20,
  },
});

chats = messaging_api.get_chats_list(
    "acc_123456789",
    limit=20,
)

To get a single chat, use Get a Chat.

const { data, error } = await messagingApi.getChat({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
  },
});

chat = messaging_api.get_chat("chat_id", "acc_123456789")

WhatsApp user and chat IDs

WhatsApp may return a user's primary ID as an LID ending in @lid, rather than as a phone-number JID ending in @s.whatsapp.net. This is expected: use the id values returned by Unipile unchanged in subsequent requests, including chat_id and user_id.

When the phone number is available, it is exposed separately as public_identifier. For a new conversation where you only know the phone number, continue to use the [email protected] format. Do not derive or replace an ID from its other form yourself; Unipile resolves the LID/phone-number mapping when needed.

Get Messages

To list messages of a Chat, use List all Chat Messages method and provide the chat ID.

const { data, error } = await messagingApi.getMessagesList({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
  },
  query: {
    limit: 20,
  },
});

messages = messaging_api.get_messages_list(
    "chat_id",
    "acc_123456789",
    limit=20,
)

curl --request GET \
     --url https://api.unipile.com/v2/account_id/chats/chat_id/messages \
     --header 'accept: application/json'

To get a single Message, use Get a Message method and provide the chat ID with the message ID.

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

message = messaging_api.get_message(
    "chat_id",
    "message_id",
    "acc_123456789",
)

curl --request GET \
     --url https://api.unipile.com/v2/account_id/chats/chat_id/messages/message_id \
     --header 'accept: application/json'

Be notified about new messages

To receive new upserted messages, setup a Webhook that listen for message.new events.

You'll be notified about any received message, but also any sent messages. This can be useful for your application to be aware of messages sent by the account owner from other devices. To ignore those messages, filter events on the is_sender value of the Message object.

Find a conversation with a user

Use Find Chats by User with a provider user ID when you already know the contact and need their conversation. This avoids scanning every page of the chat list.

const { data } = await messagingApi.getUserChat({
  path: {
    account_id: "acc_123456789",
    user_id: "user_id",
  },
});

data = messaging_api.get_user_chat(
    account_id='acc_123456789',
    user_id='user_id',
)

curl --request GET \
  --url "https://api.unipile.com/v2/acc_123456789/users/user_id/chat" \
  --header 'X-API-KEY: YOUR_API_KEY'

Retrieve contacts

Use List all Contacts to retrieve contacts exposed by the connected WhatsApp account. Keep the returned provider identifiers for profile and conversation methods; a contact result does not guarantee that a conversation already exists.

const { data } = await messagingApi.getContactsList({
  path: {
    account_id: "acc_123456789",
  },
});

import requests

response = requests.get(
    "https://api.unipile.com/v2/acc_123456789/contacts",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
data = response.json()

curl --request GET \
  --url "https://api.unipile.com/v2/acc_123456789/contacts" \
  --header 'X-API-KEY: YOUR_API_KEY'

Delete a conversation

Delete a Chat removes the selected chat. This is separate from Delete a Message, which targets one message. Choose the operation matching the user's intended action.

const { data } = await messagingApi.deleteChat({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
  },
});

data = messaging_api.delete_chat(
    account_id='acc_123456789',
    chat_id='chat_id',
)

curl --request DELETE \
  --url "https://api.unipile.com/v2/acc_123456789/chats/chat_id" \
  --header 'X-API-KEY: YOUR_API_KEY'