---
updatedAt: 2026-08-06T09:23:51.000Z
agentTools:
  projectIndex: https://developers.alcmeon.com/llms.txt
---

# Start Scenario

Start a scenario for a specific user


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "servers": [
    {
      "url": "https://api.alcmeon.com/",
      "description": "Production api server"
    }
  ],
  "info": {
    "title": "Scenarios",
    "version": "1.0"
  },
  "x-readme": {
    "explorer-enabled": true
  },
  "components": {
    "securitySchemes": {
      "basic_auth": {
        "description": "Basic authentication using your environment Instance ID as username and Application Secret as password.\n",
        "type": "http",
        "scheme": "basic"
      },
      "bearer_token": {
        "description": "OAuth 2.0 Bearer token authentication.  Obtain a token by calling the /v1/oauth2/token endpoint with your credentials. The token is valid for one hour.\n",
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "RateLimitResponseError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Rate limit reached"
          },
          "details": {
            "type": "string",
            "description": "A string showing the time when the rate limit will be reset. Example: {'rate_limited_until': '2024-01-22T13:05:41Z'}\n"
          }
        }
      }
    }
  },
  "security": [
    {
      "basic_auth": []
    },
    {
      "bearer_token": []
    }
  ],
  "paths": {
    "/start-scenario": {
      "post": {
        "summary": "Start Scenario",
        "description": "Start a scenario for a specific user\n",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "starting_box": {
                    "description": "The unique id associated with the scenario entry point you would like to trigger. The format of this value is opaque and subject to change for new scenarios without notice.  The proper value can be found in the scenario editor by clicking in the top-right corner of a box and selecting the \"Copy identifier\" entry  in the menu.\n",
                    "type": "string"
                  },
                  "variables": {
                    "type": "object",
                    "description": "A set of key/value pairs that will be stored in the user-specific variables used  within the scenario. If you are unsure about what to store in this field, leave this dictionnary empty.\n"
                  },
                  "user": {
                    "type": "object",
                    "properties": {
                      "social_media_user_id": {
                        "type": "string",
                        "description": "The id associated with the user within the social media associated with the scenario. On Whatsapp, this is the user's phone number, in international format, without a leading +. For example a french phone number in this format will look like this 33672422826  (33 is the international prefix). Failure to provide an id in the correct format will be silently ignored and return a 200 status.\n"
                      }
                    },
                    "required": [
                      "social_media_user_id"
                    ]
                  },
                  "interrupt_ongoing_conversation": {
                    "type": "boolean",
                    "description": "If you want to force the message even if the user already has an ongoing conversation with the brand. For more details about blocking message when a user has an ongoing conversation, [check our documentation](https://help.alcmeon.ai/)",
                    "default": false
                  }
                },
                "required": [
                  "starting_box",
                  "user"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returned upon succes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Returned if the request body format is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "A short string explaining the reason of the error."
                    },
                    "details": {
                      "type": "string",
                      "description": "A short string which describes what is wrong. Provide this string to  support@alcmeon.com if you wish to obtain more details about the problem.\n"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Returned if the user you are trying to reach is not accessible due to an ongoing conversation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "A short string explaining the reason of the error."
                    },
                    "details": {
                      "type": "string",
                      "description": "A short string which describes what is wrong. Provide this string to  support@alcmeon.com if you wish to obtain more details about the problem.\n"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached. For this route limit is 2000 requests per minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitResponseError"
                }
              }
            }
          }
        }
      }
    }
  }
}
```