> ## Documentation Index > Fetch the complete documentation index at: https://docs.hookmyapp.com/llms.txt > Use this file to discover all available pages before exploring further. # List recent channel events > Recent events on the channel in the same shape a subscription receives, with `raw` set to null and `rawOmitted` true, limited to what your plan lets you see in the delivery log. Returns up to `limit` of the most recent events, newest first. It looks through a bounded number of recent deliveries, so it can return fewer than `limit` events when the type you asked for is rare. Use it as sample data when you set up an automation, not as a history feed: no paging. Facebook Page channels return an empty list. ## OpenAPI ````yaml api-reference/openapi.yaml GET /channels/{ch}/events openapi: 3.1.0 info: title: HookMyApp API version: 1.0.0 description: > The HookMyApp REST API. Everything the dashboard and the CLI can do, your code and your AI agents can do too. ## Authentication Two kinds of Bearer credentials exist. Do not mix them up: - **API key (`hmok_...`)** authenticates *you* (or your agent) to `https://api.hookmyapp.com`. Create one in the dashboard under **Org → API keys → Create API Key** (full org access, optional expiration date, reveal or revoke it any time from that page), or without a browser via the [agent auth flow](#tag/agent-auth) described in [`GET /auth.md`](https://api.hookmyapp.com/auth.md). That flow can mint a scope-limited key. Send it as `Authorization: Bearer hmok_...`, or on `/mcp` as `X-API-Key: hmok_...`. Use it for org, workspace, customer, channel and webhook management. - **Channel token (`hmat_...`)** sends messages, replies to comments, and publishes from one connected channel. Mint it with `GET /meta/channels/{id}/token`. It is not valid on `https://api.hookmyapp.com`. The same sends, replies and publishing are also available with the API key under `/channels/{ch}` (see the Channel actions tag). Browser sessions from the dashboard use the same endpoints with a session cookie or WorkOS JWT instead of `hmok_`. ## IDs Every ID on the wire is a typed public ID, never an internal UUID: `ws_` workspace/customer, `ch_` channel, `org_` organization, `cred_` connection credential, `ac_` agent credential. ## Workspace context Workspace-scoped routes (channels, webhook config, and deliveries) resolve the workspace from the `X-Workspace-Id: ws_XXXXXXXX` header. ## Errors Errors return a stable machine-readable `code` plus a human `message`. Agent tokens that exceed their granted scopes get `403 AGENT_SCOPE_INSUFFICIENT`. ## Webhook signatures Deliveries to your webhook are signed with `X-HookMyApp-Signature-256`, an HMAC-SHA256 of the raw body keyed on the channel `WEBHOOK_HMAC_SECRET`. The Verify Token is a separate value used only for the GET ownership probe. servers: - url: https://api.hookmyapp.com description: Production security: - bearerAuth: [] tags: - name: Agent auth description: Register an agent credential (`hmok_`) with email OTP, no browser needed - name: Organizations description: Your organization and its summary - name: Customers description: Customer workspaces you run messaging for (SaaS Mode) - name: Onboarding links description: Links your customers open to connect their own channels - name: Workspaces description: Team workspaces - name: Channels description: Connected WhatsApp and Instagram channels, and their channel tokens - name: Webhook config description: Where inbound events are delivered for a channel - name: Deliveries description: Inspect inbound delivery logs and app responses - name: Event subscriptions description: >- Extra URLs that receive a channel's events, next to its main webhook destination - name: Channel actions description: >- Send, reply, moderate and publish on a channel with the API key; the channel token stays server-side paths: /channels/{ch}/events: get: tags: - Event subscriptions summary: List recent channel events description: > Recent events on the channel in the same shape a subscription receives, with `raw` set to null and `rawOmitted` true, limited to what your plan lets you see in the delivery log. Returns up to `limit` of the most recent events, newest first. It looks through a bounded number of recent deliveries, so it can return fewer than `limit` events when the type you asked for is rare. Use it as sample data when you set up an automation, not as a history feed: no paging. Facebook Page channels return an empty list. operationId: listChannelEvents parameters: - name: ch in: path required: true schema: type: string pattern: ^ch_[A-Za-z0-9]{8}$ description: ch_ channel id - in: query name: types schema: type: string description: 'Comma-separated event types. Default: all.' example: whatsapp.message.received - in: query name: limit schema: type: integer minimum: 1 maximum: 50 default: 10 description: Out-of-range values are clamped. responses: '200': description: Events content: application/json: schema: type: object required: - events properties: events: type: array items: $ref: '#/components/schemas/ChannelEvent' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': $ref: '#/components/responses/Error' components: schemas: ChannelEvent: oneOf: - $ref: '#/components/schemas/WhatsAppMessageReceivedEvent' - $ref: '#/components/schemas/WhatsAppMessageStatusEvent' - $ref: '#/components/schemas/InstagramMessageReceivedEvent' - $ref: '#/components/schemas/InstagramCommentReceivedEvent' discriminator: propertyName: type mapping: whatsapp.message.received: $ref: '#/components/schemas/WhatsAppMessageReceivedEvent' whatsapp.message.status: $ref: '#/components/schemas/WhatsAppMessageStatusEvent' instagram.message.received: $ref: '#/components/schemas/InstagramMessageReceivedEvent' instagram.comment.received: $ref: '#/components/schemas/InstagramCommentReceivedEvent' WhatsAppMessageReceivedEvent: allOf: - $ref: '#/components/schemas/ChannelEventEnvelope' - type: object properties: type: const: whatsapp.message.received data: type: object required: - messageId - from - contactName - timestamp - messageType - text - media - interactive - context properties: messageId: type: string from: type: string description: Sender phone number contactName: type: - string - 'null' timestamp: type: string format: date-time messageType: type: string description: Meta message type, e.g. text, image, interactive text: type: - string - 'null' description: Text body or media caption media: type: - object - 'null' required: - id - mimeType - sha256 - filename properties: id: type: - string - 'null' mimeType: type: - string - 'null' sha256: type: - string - 'null' filename: type: - string - 'null' interactive: type: - object - 'null' description: Button or list reply, as Meta sends it context: type: - object - 'null' required: - messageId properties: messageId: type: string description: The message this one replies to WhatsAppMessageStatusEvent: allOf: - $ref: '#/components/schemas/ChannelEventEnvelope' - type: object properties: type: const: whatsapp.message.status data: type: object required: - messageId - recipient - status - timestamp - error properties: messageId: type: string recipient: type: string status: type: string enum: - sent - delivered - read - failed timestamp: type: string format: date-time error: type: - object - 'null' required: - code - title properties: code: type: - integer - 'null' title: type: - string - 'null' InstagramMessageReceivedEvent: allOf: - $ref: '#/components/schemas/ChannelEventEnvelope' - type: object properties: type: const: instagram.message.received data: type: object required: - messageId - from - timestamp - text - attachments - quickReplyPayload properties: messageId: type: string from: type: string description: Sender Instagram-scoped id timestamp: type: string format: date-time text: type: - string - 'null' attachments: type: array items: type: object required: - type - url properties: type: type: - string - 'null' url: type: - string - 'null' quickReplyPayload: type: - string - 'null' InstagramCommentReceivedEvent: allOf: - $ref: '#/components/schemas/ChannelEventEnvelope' - type: object properties: type: const: instagram.comment.received data: type: object required: - commentId - mediaId - from - text - timestamp - parentCommentId - isLive - mentionsChannel properties: commentId: type: string mediaId: type: - string - 'null' description: null for comments on a live video from: type: - object - 'null' required: - id - username properties: id: type: - string - 'null' username: type: - string - 'null' text: type: - string - 'null' timestamp: type: - string - 'null' format: date-time parentCommentId: type: - string - 'null' isLive: type: boolean description: >- true for a comment on a live video. Always present (spec D4). mentionsChannel: type: boolean description: true when the comment tags your account Error: type: object properties: statusCode: type: integer example: 403 description: HTTP status code mirrors the response status: null code: type: string description: Stable machine-readable code, e.g. `AGENT_SCOPE_INSUFFICIENT` message: type: string requestId: type: string description: Include this when contacting support about the request ChannelEventEnvelope: type: object required: - id - type - occurredAt - channelId - channel - data - raw - rawOmitted properties: id: type: string description: >- `evt_` id. The same event always has the same id: use it to drop duplicates. type: $ref: '#/components/schemas/ChannelEventType' occurredAt: type: - string - 'null' format: date-time description: When it happened per Meta; null when Meta sends no time. channelId: type: string description: ch_ channel id channel: type: object required: - type properties: type: type: string enum: - whatsapp - instagram data: type: object raw: description: >- The payload your main webhook receives for this event; null when omitted. rawOmitted: type: boolean description: >- true when raw is null because the event including raw exceeded 256 KB (always true on GET /channels/{ch}/events). ChannelEventType: type: string enum: - whatsapp.message.received - whatsapp.message.status - instagram.message.received - instagram.comment.received responses: Error: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: '`Authorization: Bearer hmok_...` API key or a dashboard session token' ````