> ## Documentation Index > Fetch the complete documentation index at: https://messages.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get typing indicators > Returns current typing indicators for a chat. ## OpenAPI ````yaml GET /v1/typing openapi: 3.1.0 info: title: Messages.dev API version: '1.0' description: > The Messages.dev API lets you send and receive iMessages programmatically. ## Recommended: use the TypeScript SDK `@messages-dev/sdk` (`npm install @messages-dev/sdk`) is the recommended integration for TypeScript and Node.js. It wraps every endpoint below with a typed client, handles cursor pagination, throws typed errors, and ships `verifyWebhook()` which gets the HMAC scheme right (`HMAC(${timestamp}.${body})` with replay protection). See the [SDK reference](/sdk). The REST API documented here is the underlying transport — use it directly from any language without TypeScript. ## Conventions All endpoints are prefixed with `/v1` and return JSON. Request and response fields use `snake_case`. All IDs include a type prefix (e.g. `msg_`, `cht_`). Write operations (POST /messages, /audio-messages, /reactions, /typing, /receipts) are **asynchronous**. They return a delivery ID with `status: "pending"`. Use `GET /outbox` or webhooks to track delivery. ## Capabilities - Send and receive text messages, with optional file attachments and reply-to threading. - Send native iMessage **audio messages** (waveform balloon) via `POST /v1/audio-messages`. Inbound voice memos arrive on `message.received` with `is_audio_message: true` and include Apple's on-device `transcription`. - Send **iMessage reactions** (`love`, `like`, `dislike`, `laugh`, `emphasize`, `question`) via `POST /v1/reactions`. Receive inbound reactions via the `reaction.added` / `reaction.removed` webhooks. - Send **typing indicators** and **read receipts**. - Upload files and send them as attachments (or as **vCard contact cards** — see Recipes). - **Group chats**: send to a `cht_...` chat ID returned by `GET /v1/chats`. - **Webhooks** for `message.received`, `message.sent`, `reaction.added`, `reaction.removed`. Signed with HMAC-SHA256 over `${timestamp}.${body}`. ## Contact-first restriction To protect lines from being flagged as spammers, you can only send to a contact after they have messaged your line first. Attempting to send to a contact that has not messaged in returns `403 contact_has_not_messaged`. The sandbox line is pre-paired with your phone number once you activate it. ## Recipes A few capabilities are compositions of existing endpoints rather than a dedicated route. The SDK wraps each as a single call. | Capability | Mechanism | SDK helper | |---|---|---| | Send a contact card | `POST /v1/files` (`Content-Type: text/vcard`) → `POST /v1/messages` with the returned file ID in `attachments` | `client.sendContactCard()` | | Send a native audio message | `POST /v1/files` (audio mime) → `POST /v1/audio-messages` with the file ID as `audio_message` | `client.sendAudioMessage()` | | Reply to a specific message | `POST /v1/messages` with `reply_to: "msg_..."` (or a raw iMessage GUID) | `replyTo` parameter on every send method | | Send into a group chat | `POST /v1/messages` with a `cht_...` chat ID as `to`. Discover chats via `GET /v1/chats`. | Same `to` parameter | | Test webhooks locally | Build a real signed delivery yourself, then POST it to your handler — `verifyWebhook()` accepts it without a test-mode flag. | `signWebhook` / `buildWebhookDelivery` | servers: - url: https://api.messages.dev description: Messages.dev API security: - BearerAuth: [] tags: - name: Lines description: Your iMessage phone numbers and Apple IDs - name: Chats description: Conversations on a line - name: Messages description: Send and retrieve messages - name: Reactions description: iMessage reactions (love, like, etc.) on messages - name: Typing description: Typing indicators - name: Read Receipts description: Read receipt tracking - name: Delivery description: Track delivery status of write operations - name: Files description: Upload and retrieve file attachments - name: Webhooks description: Real-time event notifications paths: /v1/typing: get: tags: - Typing summary: Get typing indicators description: Returns current typing indicators for a chat. operationId: get-typing-indicators parameters: - $ref: '#/components/parameters/from' - $ref: '#/components/parameters/to' responses: '200': description: List of typing indicators content: application/json: schema: allOf: - $ref: '#/components/schemas/ListResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/TypingIndicator' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: from: name: from in: query required: true description: Line handle (phone number or Apple ID) schema: type: string example: '+15551234567' to: name: to in: query required: true description: Chat identifier (phone number, Apple ID, or chat ID) schema: type: string example: '+15559876543' schemas: ListResponse: type: object properties: data: type: array items: {} has_more: type: boolean description: Whether more items exist beyond this page next_cursor: type: - string - 'null' description: Cursor to pass as `cursor` query parameter for the next page request_id: type: string TypingIndicator: type: object properties: id: type: string description: Typing indicator ID (e.g. `ind_abc123`) chat_id: type: string handle: type: string description: Handle of the person typing is_typing: type: boolean updated_at: type: number Error: type: object properties: error: type: object properties: type: type: string description: Error category enum: - authentication_error - authorization_error - invalid_request_error - not_found_error - rate_limit_error code: type: string description: Machine-readable error code message: type: string description: Human-readable error description param: type: string description: The parameter that caused the error, if applicable request_id: type: string description: Unique request identifier for debugging responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: missing_required_parameter message: The 'from' query parameter is required. param: from request_id: req_abc123 Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: authentication_error code: missing_api_key message: >- Missing Authorization header. Use 'Authorization: Bearer sk_live_...' request_id: req_abc123 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: not_found_error code: line_not_found message: Line not found. param: from request_id: req_abc123 securitySchemes: BearerAuth: type: http scheme: bearer description: | Use an API key as a bearer token: `Authorization: Bearer sk_live_...` Each key has a set of scopes that gate which endpoints it can call: `messages:read`, `messages:write`, `chats:read`, `lines:read`, `reactions:read`, `reactions:write`, `typing:read`, `typing:write`, `receipts:read`, `receipts:write`, `webhooks:read`, `webhooks:write`, `outbox:read`, `files:read`, `files:write`. Keys can also be restricted to a subset of lines. ````