> ## 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. # Send typing indicator > Sends a typing indicator to a chat. Returns a delivery ID with `status: "pending"`. ## OpenAPI ````yaml POST /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: post: tags: - Typing summary: Send typing indicator description: | Sends a typing indicator to a chat. Returns a delivery ID with `status: "pending"`. operationId: send-typing-indicator requestBody: required: true content: application/json: schema: type: object required: - from - to properties: from: type: string description: Sender line handle (phone number or Apple ID) example: '+15551234567' to: type: string description: Recipient handle example: '+15559876543' state: type: string description: Typing state. Defaults to `on`. enum: - 'on' - 'off' default: 'on' responses: '201': description: Outbox item created content: application/json: schema: $ref: '#/components/schemas/OutboxItemCreated' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: OutboxItemCreated: type: object properties: id: type: string description: Delivery ID (e.g. `obx_abc123`) status: type: string const: pending request_id: type: string 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 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. ````