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

# Create SMS Conversation

> Create an SMS conversation with specific pathway state without triggering immediate message sending.

> [!NOTE]
>
> **Enterprise Feature** - SMS is only available on Enterprise plans. Contact your Bland representative for access.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

**user\_number** `string` *required*

The E.164 formatted phone number of the user in the conversation.

**agent\_number** `string` *required*

The E.164 formatted phone number used by the agent (must belong to the authenticated account).

**message** `string` *required*

The content of the message to be stored in the conversation history.

**message\_sid** `string`

Optional Twilio message SID for tracking and correlation purposes.

**curr\_pathway\_id** `string`

The UUID of the current pathway being used in this conversation.

**curr\_pathway\_version** `string`

The specific version of the pathway to use (e.g., "latest", "v1.0").

**current\_node\_id** `string`

The ID of the current node in the conversational pathway where this conversation is positioned.

**request\_data** `object`

Optional metadata to associate with the conversation. Used for custom routing or analytics.

**new\_conversation** `boolean`

When set to true, forces creation of a new conversation, archiving any existing active conversation between these numbers.

**sender** `string`

Specifies who sent this message. Allowed values: "USER" or "AGENT". Defaults to "USER" if not specified.

**time\_out** `number`

Per-conversation timeout override, in seconds. When the user goes silent for this long after an agent message, the timeout flow fires (warning message and/or conversation end). Takes priority over the `time_out` on the number's sms\_config/whatsapp\_config. Persists on the conversation, so subsequent turns use the same override until another `/send` or `/create` replaces it.

**timeout\_message** `string`

Per-conversation override for the message sent when the timeout fires. Takes priority over `timeout_message` on sms\_config/whatsapp\_config.

**warning\_time** `number`

Per-conversation override for how long, in seconds, to wait before sending the warning message. Must be less than `time_out`; the request is rejected with `INVALID_TIMEOUT_CONFIG` otherwise. Takes priority over `warning_time` on sms\_config/whatsapp\_config.

**warning\_message** `string`

Per-conversation override for the warning message sent at `warning_time`. Takes priority over `warning_message` on sms\_config/whatsapp\_config.

### Response

**data** `object`

An object confirming the conversation was created successfully.

**data.message** `string`

Confirmation text for the successful conversation creation.

**data.conversation\_id** `string`

ID of the conversation that was created.

**data.workflow\_id** `string`

ID of the Temporal workflow triggered to process the conversation setup.

**errors** `null|array`

`null` on success, or a list of error objects if the request failed.

```json Response theme={null}
{
  "data": {
    "message": "SMS conversation created successfully",
    "conversation_id": "conv_abc123",
    "workflow_id": "workflow_xyz789"
  },
  "errors": null
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.