---
title: "Simulate Inbound User Event"
method: POST
path: "/messages/simulate/user"
tags: ["Messages > simulate"]
---

# Simulate Inbound User Event

`POST /messages/simulate/user`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/messages/simulate/user`
- Auth: API key in header `PINNACLE-API-KEY`

Simulate inbound messages and button presses from a user.

## Request body

- union: Request body for simulating an inbound event from a user.
  - SimulateUserMessageRequest: Simulate an inbound message from a user.
    - `from` string, required: User phone number in E.164 format.
    - `to` string, required: Receiver phone number in E.164 format or RCS agent ID (prefixed with `agent_`).
    - `message` SimulateMessageInput, required: 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.
      - `text` string: Text message sent by the user.
      - `mediaUrls` string[]: URLs of media files sent by the user.
  - SimulateUserButtonRequest: Simulate a button press from a user.
    - `from` string, required: User phone number in E.164 format.
    - `to` string, required: RCS agent ID (prefixed with `agent_`).
    - `button` union, required: Discriminated union of button presses that can be simulated for a user.
      - object: Simulates when a user presses a `trigger` button.
        - `type` 'trigger', required: Discriminator value: trigger
        - `title` string, required: Name of the button that you want to press.
        - `metadata` string: Metadata attached to the button.
        - `payload` string: Button's postback payload.
      - object: Simulates when a user presses an `openUrl` button.
        - `type` 'openUrl', required: Discriminator value: openUrl
        - `title` string, required: Name of the button that you want to press.
        - `metadata` string: Metadata attached to the button.
        - `payload` string: Destination URL of the tapped button.
      - object: Simulates when a user presses a `call` button.
        - `type` 'call', required: Discriminator value: call
        - `title` string, required: Name of the button that you want to press.
        - `metadata` string: Metadata attached to the button.
        - `payload` string: Destination phone number in E.164 format.
      - object: Simulates when a user presses a `scheduleEvent` button.
        - `type` 'scheduleEvent', required: Discriminator value: scheduleEvent
        - `title` string, required: Name of the button that you want to press.
        - `metadata` string: Metadata attached to the button.
        - `eventStartTime` string: ISO 8601 start time. Defaults to the current time.
        - `eventEndTime` string: ISO 8601 end time. Defaults to one hour after `eventStartTime`.
        - `eventTitle` string
        - `eventDescription` string
      - object: Simulates when a user presses a `sendLocation` button.
        - `type` 'sendLocation', required: Discriminator value: sendLocation
        - `title` string, required: Name of the button that you want to press.
        - `metadata` string: Metadata attached to the button.
        - `name` string: Name of the location shared.
        - `latLong` UserButtonPressDiscriminatorMappingSendLocationLatLong: Shared coordinates.
          - `lat` number, double: Latitude of the shared location.
          - `lng` number, double: Longitude of the shared location.
      - object: Simulates when a user presses a `requestUserLocation` button.
        - `type` 'requestUserLocation', required: Discriminator value: requestUserLocation
        - `title` string, required: Name of the button that you want to press.
        - `metadata` string: Metadata attached to the button.
        - `location` UserButtonPressDiscriminatorMappingRequestUserLocationLocation: Location the simulated user responded with.
          - `text` string
          - `latitude` number, double
          - `longitude` number, double
          - `address` string

## Response `200`

Returns simulation result.

- SimulateUserResponse: Result of the simulation.
  - `success` boolean, required

## Other responses

- `400`: The request was unacceptable, often due to providing an invalid update. <br> 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. <br> 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.<br> 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.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)