# Simulate Inbound User Event

`POST /messages/simulate/user`

Simulate inbound messages and button presses from a user.

## Authentication

Send your API key in the `PINNACLE-API-KEY` header.

## Request body

Required.

Content type: `application/json`.

### Fields

- Variant: Inbound Message
- `from` — `string`. User phone number in E.164 format.
- `to` — `string`. Receiver phone number in E.164 format or RCS agent ID (prefixed with `agent_`).
- `message` — `SimulateMessageInput`. User message payload. At least one of `text` or `mediaUrls` must be non-empty.
Send only `text` to simulate an inbound SMS; include `mediaUrls` to simulate an inbound MMS.
- `message.text` — `string`, optional. Text message sent by the user.
- `message.mediaUrls` — `string[]`, optional. URLs of media files sent by the user.
- Variant: Inbound Button Clicked
- `from` — `string`. User phone number in E.164 format.
- `to` — `string`. RCS agent ID (prefixed with `agent_`).
- `button` — `UserButtonPress`. Discriminated union of button presses that can be simulated for a user.
- `button` Variant: trigger
- `button.type` — `string`, values: `trigger`
- `button.title` — `string`. Name of the button that you want to press.
- `button.metadata` — `string`, optional, default: "metadata". Metadata attached to the button.
- `button.payload` — `string`, optional, default: "trigger-payload"; minimum length: 1. Button's postback payload.
- `button` Variant: openUrl
- `button.type` — `string`, values: `openUrl`
- `button.title` — `string`. Name of the button that you want to press.
- `button.metadata` — `string`, optional, default: "metadata". Metadata attached to the button.
- `button.payload` — `string`, optional, default: "https://www.pinnacle.sh/". Destination URL of the tapped button.
- `button` Variant: call
- `button.type` — `string`, values: `call`
- `button.title` — `string`. Name of the button that you want to press.
- `button.metadata` — `string`, optional, default: "metadata". Metadata attached to the button.
- `button.payload` — `string`, optional, default: "+15555555555". Destination phone number in E.164 format.
- `button` Variant: scheduleEvent
- `button.type` — `string`, values: `scheduleEvent`
- `button.title` — `string`. Name of the button that you want to press.
- `button.metadata` — `string`, optional, default: "metadata". Metadata attached to the button.
- `button.eventStartTime` — `string`, optional. ISO 8601 start time. Defaults to the current time.
- `button.eventEndTime` — `string`, optional. ISO 8601 end time. Defaults to one hour after `eventStartTime`.
- `button.eventTitle` — `string`, optional, default: "Scheduled Event"
- `button.eventDescription` — `string`, optional, default: "Event Description"
- `button` Variant: sendLocation
- `button.type` — `string`, values: `sendLocation`
- `button.title` — `string`. Name of the button that you want to press.
- `button.metadata` — `string`, optional, default: "metadata". Metadata attached to the button.
- `button.name` — `string`, optional, default: "Shared Location". Name of the location shared.
- `button.latLong` — `object`, optional. Shared coordinates.
- `button.latLong.lat` — `number`, optional, format: double; default: 37.7899. Latitude of the shared location.
- `button.latLong.lng` — `number`, optional, format: double; default: -122.3969. Longitude of the shared location.
- `button` Variant: requestUserLocation
- `button.type` — `string`, values: `requestUserLocation`
- `button.title` — `string`. Name of the button that you want to press.
- `button.metadata` — `string`, optional, default: "metadata". Metadata attached to the button.
- `button.location` — `object`, optional. Location the simulated user responded with.
- `button.location.text` — `string`, optional, default: "Location Provided"
- `button.location.latitude` — `number`, optional, format: double; default: 37.7899
- `button.location.longitude` — `number`, optional, format: double; default: -122.3969
- `button.location.address` — `string`, optional, default: "415 Mission St, San Francisco, CA 94105"

### Example

```json
{
  "from": "+14155551234",
  "to": "+14155555678",
  "message": {
    "text": "Hello from Pinnacle!",
    "mediaUrls": [
      "https://example.com/assets/message-image.jpg"
    ]
  }
}
```

## Responses

### 200

Returns simulation result.

Content type: `application/json`. Schema: `SimulateUserResponse`.

- `success` — `boolean`

### 400

The request was unacceptable, often due to providing an invalid update.

Errors may originate from invalid payload or from Pinnacle's additional validation checks. For example, providing an URL that cannot be accessed, updating a campaign that is currently being reviewed, updating data that you cannot access, sending a malformed message, and so on.

For `Pinnacle Validation Error` inspect the `error` payload to determine the source of the failure. These errors are likely due to additional validation and business logic checks.

For `Request Validation Error` inspect the `description` and `errors` payload to determine the source of failure. These errors are likely due to invalid payload inside the request.

Content type: `application/json`. Schema: `Request Validation Error | Pinnacle Validation Error`.

- Variant: variant 1
- `description` — `string`. Human-readable summary of validation failures.
- `errors` — `object`. Structured dictionary of issues containing two main sections:
- `errors`: Array of global validation errors not tied to specific fields
- `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array
- Variant: variant 2
- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "description": "✖ Invalid input: expected string, received number\n  → at example_field",
  "errors": {
    "errors": [],
    "properties": {
      "example_field": {
        "errors": [
          "Invalid input: expected string, received NaN"
        ]
      }
    }
  }
}
```

### 401

The request lacks valid authentication credentials or the provided credentials are invalid.

Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Invalid API key."
}
```

### 403

Your subscription does not include access to this feature.

This occurs when attempting to use functionality that requires a higher subscription tier.
Please upgrade your subscription to access this feature.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Your subscription does not include access to this feature."
}
```

### 500

An unexpected error occurred on Pinnacle's servers while processing your request.

If this error persists, please contact support with the request details.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "An unexpected error occurred while processing your request."
}
```

## SDK examples

### TypeScript

```typescript
import { PinnacleClient } from "rcs-js";

const client = new PinnacleClient({
  apiKey: process.env.PINNACLE_API_KEY!,
});

await client.messages.simulate.user({
    from: "+14155551234",
    to: "+14155555678",
    message: {
        text: "Hello from the test user!"
    }
});
```

### Python

```python
import os
from rcs import (
    Pinnacle,
    SimulateUserButton,
    UserButtonPress_RequestUserLocation,
)

client = Pinnacle(
    api_key=os.environ["PINNACLE_API_KEY"],
)

client.messages.simulate.user(
    request=SimulateUserButton(
        from_="+14155551234",
        to="agent_abc123",
        button=UserButtonPress_RequestUserLocation(
            title="Share Location",
        ),
    ),
)
```

### Ruby

```ruby
require "rcs"

client = Pinnacle::Client.new(
  api_key: ENV.fetch("PINNACLE_API_KEY")
)

client.messages.simulate.user(
  from: "+14155551234",
  to: "+14155555678",
  message: {
    text: "Hello from the test user!"
  }
)
```

## Machine-readable schema

[OpenAPI 3.1 JSON](https://docs.pinnacle.sh/openapi.json)