Get Message

TypeScript

import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: '919876543210', // the phone to act with (x-phone)
});

async function main() {
  const response = await client.messages.getMessageById({
    message_id: 'true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
  });
  console.log(response);
}

main();

{
  "message_id": "true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "unique_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "org_id": "00000000-0000-0000-0000-000000000000",
  "org_phone": "911111111111@c.us",
  "chat_id": "120363000000000000@g.us",
  "body": "Hello World",
  "message_type": "chat",
  "timestamp": "2026-01-15T09:30:00+00:00",
  "from_me": true,
  "ack": "3",
  "performed_by": "api",
  "sender_phone": "911111111111@c.us",
  "quoted_message_id": null,
  "broadcast_id": null,
  "is_deleted": null,
  "media": {
    "path": "https://example.com/files/image.png",
    "mimetype": "image/png",
    "filename": "image.png",
    "size": 24576,
    "dimensions": {
      "width": null,
      "height": null,
      "ar": null
    },
    "thumbnail": null
  },
  "mentioned_ids": [],
  "prev_body": null,
  "sent_message_id": "00000000-0000-0000-0000-000000000000",
  "delivery_info": {
    "delivered": {
      "911111111111@c.us": 1737967705196
    },
    "read": {
      "911111111111@c.us": 1737967704763
    },
    "pending": [],
    "delivered_count": 1,
    "read_count": 1
  },
  "poll_info": {},
  "poll_results": {},
  "flag_status": null,
  "updated_at": "2026-01-15T09:35:38.221+00:00",
  "reactions": [
    {
      "reaction_id": "true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAA",
      "message_id": "true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "unique_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "chat_id": "911111111111@c.us",
      "org_id": "00000000-0000-0000-0000-000000000000",
      "org_phone": "911111111111@c.us",
      "sender_id": "911111111111@c.us",
      "reaction": "😄",
      "read": true,
      "timestamp": "2026-01-15T09:31:57.008+00:00"
    }
  ]
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "code": "NOT_FOUND_ERROR",
  "message": "No message matches message_id for the phone",
  "status": 404
}

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 422,
  "fields": {
    "body.chat_id": {
      "message": "chat_id is required"
    }
  }
}

{
  "code": "RATE_LIMIT_ERROR",
  "message": "You can only make 100 requests per second",
  "status": 429
}

{
  "code": "UNKNOWN_ERROR",
  "message": "Internal server error",
  "status": 500
}

TypeScript

import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: '919876543210', // the phone to act with (x-phone)
});

async function main() {
  const response = await client.messages.getMessageById({
    message_id: 'true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
  });
  console.log(response);
}

main();

{
  "message_id": "true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "unique_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "org_id": "00000000-0000-0000-0000-000000000000",
  "org_phone": "911111111111@c.us",
  "chat_id": "120363000000000000@g.us",
  "body": "Hello World",
  "message_type": "chat",
  "timestamp": "2026-01-15T09:30:00+00:00",
  "from_me": true,
  "ack": "3",
  "performed_by": "api",
  "sender_phone": "911111111111@c.us",
  "quoted_message_id": null,
  "broadcast_id": null,
  "is_deleted": null,
  "media": {
    "path": "https://example.com/files/image.png",
    "mimetype": "image/png",
    "filename": "image.png",
    "size": 24576,
    "dimensions": {
      "width": null,
      "height": null,
      "ar": null
    },
    "thumbnail": null
  },
  "mentioned_ids": [],
  "prev_body": null,
  "sent_message_id": "00000000-0000-0000-0000-000000000000",
  "delivery_info": {
    "delivered": {
      "911111111111@c.us": 1737967705196
    },
    "read": {
      "911111111111@c.us": 1737967704763
    },
    "pending": [],
    "delivered_count": 1,
    "read_count": 1
  },
  "poll_info": {},
  "poll_results": {},
  "flag_status": null,
  "updated_at": "2026-01-15T09:35:38.221+00:00",
  "reactions": [
    {
      "reaction_id": "true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAA",
      "message_id": "true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "unique_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "chat_id": "911111111111@c.us",
      "org_id": "00000000-0000-0000-0000-000000000000",
      "org_phone": "911111111111@c.us",
      "sender_id": "911111111111@c.us",
      "reaction": "😄",
      "read": true,
      "timestamp": "2026-01-15T09:31:57.008+00:00"
    }
  ]
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "code": "NOT_FOUND_ERROR",
  "message": "No message matches message_id for the phone",
  "status": 404
}

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 422,
  "fields": {
    "body.chat_id": {
      "message": "chat_id is required"
    }
  }
}

{
  "code": "RATE_LIMIT_ERROR",
  "message": "You can only make 100 requests per second",
  "status": 429
}

{
  "code": "UNKNOWN_ERROR",
  "message": "Internal server error",
  "status": 500
}

Authorizations

Authorization

string

header

required

Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.

Headers

x-phone

string

Optional. Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to let the API select an eligible phone automatically — within the token's phone scopes and connected; chat actions use a phone that has the chat (a group admin where required), message actions use the phone the message belongs to.

Example:

"919876543210"

Path Parameters

message_id

string

required

The message_id (true_... / false..._) of the message, or the unique_id returned when the message was sent via the API. The lookup is scoped to the phone in the x-phone header.

Minimum string length: 1

Example:

"true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

Response

The message record

A WhatsApp message record. Responses may include additional raw fields of the underlying record (id, author, links, location, vcards, is_forwarded, has_media, message_ticket_id, ...).

message_id

string

WhatsApp message id, in the form <from_me><chat_id>. Accepted wherever a message_id path parameter is expected.

Example:

"true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

unique_id

string

Provisional id assigned when the message was queued via the API — the same value returned by POST /message/send. Also accepted wherever a message_id path parameter is expected. null for messages that did not originate from the API.

Example:

"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

org_id

string

Id of the organization the message belongs to

Example:

"00000000-0000-0000-0000-000000000000"

org_phone

string

Org phone (WhatsApp account) the message was sent or received on, suffixed with @c.us

Example:

"911111111111@c.us"

chat_id

string

Chat the message belongs to — @c.us for 1-1 chats, @g.us for group chats

Example:

"120363000000000000@g.us"

body

string

Text content of the message, or the caption for media messages. null when the message has no text.

Example:

"Hello World"

message_type

string

Content type of the message: 'chat' for text, or e.g. 'image', 'video', 'document', 'audio', 'ptt', 'poll_creation', 'location', 'vcard'

Example:

"chat"

timestamp

string

When the message was sent, as an ISO 8601 timestamp

Example:

"2026-01-15T09:30:00+00:00"

from_me

boolean

Whether the message was sent by the org phone (true) or received from the contact (false)

Example:

true

ack

string

Delivery acknowledgement level as a string: '-1' failed, '0' pending, '1' sent, '2'/'3' delivered, '4' read, '5' played. null when unknown.

Example:

"3"

performed_by

string

Who triggered the message from Periskope: a member's email, or 'api' when sent via the API. null for messages sent from the phone itself.

Example:

"api"

sender_phone

string

chat_id of the actual sender — in group chats this is the participant who sent the message

Example:

"911111111111@c.us"

quoted_message_id

string

message_id of the message this one replies to (set via reply_to when sending). null when not a reply.

Example:

null

broadcast_id

string

Id of the broadcast that produced this message, when it was sent via POST /message/broadcast. null otherwise.

Example:

null

is_deleted

boolean

Whether the message has been deleted for everyone. null when never deleted.

Example:

null

media

object

Media attached to the message. null for text-only messages.

Show child attributes

mentioned_ids

string[]

chat_ids of the participants mentioned in the message

Example:

[]

prev_body

string

Previous text content, kept when the message was edited. null when never edited.

Example:

null

sent_message_id

string

Internal queue job id (queue_id) that produced this message when it was sent through the message queue. null otherwise.

Example:

"00000000-0000-0000-0000-000000000000"

delivery_info

object

Per-recipient delivery and read receipts. null when no receipts have been recorded.

Show child attributes

poll_info

object

The poll definition ({pollName, pollOptions, options}) for poll_creation messages. null otherwise.

poll_results

object

Votes cast on the poll, as a map of option name to voters. null for non-poll messages.

flag_status

boolean

Whether the message is currently flagged for follow-up in Periskope. null when never flagged.

Example:

null

updated_at

string

When the message record was last updated, as an ISO 8601 timestamp

Example:

"2026-01-15T09:35:38.221+00:00"

reactions

object[]

Reactions placed on the message. Present on GET /message/{message_id}; an empty array when there are none.

Show child attributes

API

Chat APIs

Group Settings APIs

Message APIs

Scheduled Message APIs

Media APIs

Contact APIs

Ticket APIs

Custom Property APIs

Task APIs

Queue APIs

Phone APIs

Notes APIs

Reaction APIs

Knowledge Base APIs

Member APIs

AI APIs

Webhook APIs

Webhooks

Authorizations

Headers

Path Parameters

Response