> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Typing Indicator

> Start a short iMessage typing signal before sending a message. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full.

<Note>
  This endpoint is best-effort visual polish. It should not block your send flow. Native clients and BlueBubbles can clear typing on their own timing.
</Note>

## When To Use This Endpoint

Use typing when you want your integration to feel more natural right before a real reply.

Common usage:

1. your system decides it is about to respond
2. you call `POST /api/messages/typing`
3. you wait a short moment
4. you send the actual message

Typing should be treated as visual sugar, not a required part of delivery.

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

***

## Request body

<ParamField body="messageId" type="string">
  Required. A Tuco message id in your workspace. Tuco uses it to resolve the correct line and chat target.
</ParamField>

***

## Start typing

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/messages/typing" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "6a07878bafb1789f8fcb68e6"
  }'
```

### Success (`200 OK`)

```json theme={null}
{
  "ok": true,
  "typing": true,
  "note": "Typing started. BlueBubbles clears typing automatically; use this as a short pre-send signal."
}
```

***

## Stop typing

Use the same endpoint with `DELETE`.

```bash theme={null}
curl -X DELETE "https://app.tuco.ai/api/messages/typing" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "6a07878bafb1789f8fcb68e6"
  }'
```

### Success (`200 OK`)

```json theme={null}
{
  "ok": true,
  "typing": false,
  "note": "Stop-typing sent best-effort. Native clients may clear typing on their own timing."
}
```

***

## Error responses

| Status | When                                              | Body                                    |
| ------ | ------------------------------------------------- | --------------------------------------- |
| `400`  | Message cannot be resolved to a valid chat target | `{ "error": "..." }`                    |
| `401`  | Missing or invalid API key / session              | `{ "error": "Unauthorized" }`           |
| `502`  | BlueBubbles returned an upstream error            | `{ "error": "BlueBubbles error: ..." }` |

***

## Notes

* Use typing shortly before a real send.
* Treat stop-typing as best effort only.
* Do not depend on typing indicators for delivery correctness.
* The most reliable way to end typing is still sending the real message.