# useDocyrusInstantMessageComposer
URL: /docs/native/hooks/use-docyrus-instant-message-composer

Wires the native InstantMessageComposer to the Docyrus SMS and WhatsApp messaging API.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-instant-message-composer
```

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)

A verbatim port of the web hook. It loads `GET /v1/messaging/sms/accounts` and `GET /v1/messaging/whatsapp/accounts` (only for the `availableChannels`), auto-selects the first account per channel, and sends through `POST …/sms/accounts/{accountId}/send` or `…/whatsapp/accounts/{accountId}/send`. WhatsApp supports `text` and pre-approved `template` messages. A `QueryClientProvider` must be mounted above it.

## Usage

```tsx
import { InstantMessageComposer } from '@/components/docyrus-native/instant-message-composer';
import { useDocyrusInstantMessageComposer } from '@/hooks/docyrus-native/use-docyrus-instant-message-composer';

const { composerProps } = useDocyrusInstantMessageComposer({ client, initialRecipients: ['+905551234567'] });

```

```tsx
// WhatsApp template
await send({ channel: 'whatsapp', type: 'template', templateName: 'order_shipped', templateLanguage: 'en_US', templateParams: ['#1042'] });
```

## API Reference

### UseDocyrusInstantMessageComposerOptions

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | - | Authenticated REST client (required) |
| `initialChannel` | `'sms' \| 'whatsapp'` | `'sms'` | Initial channel |
| `availableChannels` | `ReadonlyArray<InstantMessageChannel>` | `['sms', 'whatsapp']` | Channels offered (and queried) |
| `initialRecipients` | `string[]` | `[]` | Initial recipients |
| `initialBody` | `string` | `''` | Initial body |
| `initialSmsAccountId` / `initialWhatsAppAccountId` | `string` | first account | Accounts to preselect |
| `resetOnSendSuccess` | `boolean` | `true` | Clear recipients / body / attachments after a send |
| `enabled` | `boolean` | `true` | Toggle the queries |
| `defaultFrom` | `string` | - | Default sender override |
| `defaultPhoneNumberId` | `string` | - | Default Meta WhatsApp Cloud phone number id |
| `listSmsAccountsEndpoint` / `listWhatsAppAccountsEndpoint` | `string` | `/v1/messaging/{sms,whatsapp}/accounts` | Account endpoints |
| `sendSmsEndpoint` / `sendWhatsAppEndpoint` | `string` | `…/accounts/{accountId}/send` | Send endpoints |

### UseDocyrusInstantMessageComposerResult

| Field | Type | Description |
|-------|------|-------------|
| `composerProps` | `Pick<InstantMessageComposerProps, …>` | channel, availableChannels, recipients, body, attachments + handlers, onSend, sending |
| `channel` / `setChannel` | | Active channel |
| `smsAccounts` / `whatsAppAccounts` | `DocyrusSmsAccount[]` / `DocyrusWhatsAppAccount[]` | Account DTOs |
| `selectedSmsAccount` / `selectedWhatsAppAccount` / `selectedAccountId` | | Selection |
| `setSelectedSmsAccountId` / `setSelectedWhatsAppAccountId` | `(id: string) => void` | Change the account |
| `isLoadingAccounts` / `accountsError` / `refetchAccounts` | | Accounts query state |
| `recipients` / `body` / `attachments` + setters | | Composer state |
| `send` | `(overrides?: DocyrusInstantMessageSendOverrides) => Promise<DocyrusInstantMessageSendResult>` | Send |
| `isSending` / `sendError` / `lastSendResult` / `reset` | | Mutation state |

### Types

| Type | Description |
|------|-------------|
| `DocyrusSmsAccount` / `DocyrusWhatsAppAccount` | Account DTOs |
| `DocyrusInstantMessageSendOverrides` | `channel`, `to`, `body`, `from`, `accountId`, `type`, `phoneNumberId`, `templateName`, `templateLanguage`, `templateParams` |
| `DocyrusInstantMessageSendResult` | `{ messageId, provider, accepted, rejected }` |
| `WhatsAppMessageType` | `'text' \| 'template'` |