# Simulate an incoming message

Source: https://docs.vlayers.ai/reference/test/create-test-inbound

`POST /v1/test/inbound` · scope `messages:send`

Pretends a person wrote to your workspace from a reserved test address, so you can build and test replies without a real phone. Works only with a test key (`vl_test_…`). The conversation is marked `test: true`: every reply in it — yours and your agent's — is delivered to a simulated carrier, never a real one, and costs nothing.

Test addresses: `+15550100` to `+15550199` for SMS and WhatsApp, `test-1`, `test-2`, … for Telegram and Discord, any address at `test.vlayers.ai` for email.

You don't need a phone number: when your workspace has no sender on the channel, the message arrives on its free test sender, made on first use. The test sender has no agent, so its conversations start with the controller `api` (your code answers).

Requires an API key with the `messages:send` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `channel` | body | string | yes | The channel the message arrives on: `sms`, `whatsapp`, `telegram`, `discord` or `email`. |
| `from` | body | string | yes | A reserved test address: `+15550100` to `+15550199`, `test-<n>`, or an address at `test.vlayers.ai`. |
| `to` | body | string | no | Which of your senders receives it (a phone number, account address or mailbox). Leave it out to use your one sender on the channel, or your free test sender when you have none. |
| `text` | body | string | yes | What the person writes, up to 4,096 characters. |

## Request

cURL:

```bash
curl -X POST https://api.vlayers.ai/v1/test/inbound \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "from": "+15550123",
    "text": "Do you have a table for two tonight?"
  }'
```

TypeScript:

```ts
import { createVoiceLayerClient, createTestInbound } from '@voicelayer/api';

const client = createVoiceLayerClient({ apiKey: process.env.VOICELAYER_API_KEY!, throwOnError: true });

const { data } = await createTestInbound({
  client,
  body: {
    channel: 'sms',
    from: '+15550123',
    text: 'Do you have a table for two tonight?'
  }
});
console.log(data.conversationId);
```

Python:

```python
import os
import voicelayer

config = voicelayer.Configuration(access_token=os.environ["VOICELAYER_API_KEY"])
with voicelayer.ApiClient(config) as client:
    api = voicelayer.TestApi(client)
    result = api.create_test_inbound(
        create_test_inbound_request=voicelayer.CreateTestInboundRequest.from_dict({
            "channel": "sms",
            "from": "+15550123",
            "text": "Do you have a table for two tonight?",
        }),
    )
    print(result.conversation_id)
```

## Response `202`

```json
{
  "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
  "messageId": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",
  "test": true
}
```