> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt > Use this file to discover all available pages before exploring further. # Trigger test event > **Required scope:** `sandbox:write` ## OpenAPI ````yaml api-reference/features/operate.json POST /messaging/testing/{projectId}/events openapi: 3.0.3 info: title: Operate API methods version: 1.0.0 description: Task-focused operate methods across supported Polymorfa connection types. servers: [] security: [] paths: /messaging/testing/{projectId}/events: post: tags: - Testing summary: Trigger test event description: '**Required scope:** `sandbox:write`' operationId: nativeTriggerTestEvent parameters: - schema: type: string format: uuid required: true name: projectId in: path description: |- Identifier of the Polymorfa project that owns this resource. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uuid` | - schema: type: string pattern: ^[\x21-\x7e]{1,255}$ description: >- Optional. Repeating a request with the same key and body reuses the same event ID, so a retry after a failed or uncertain response never creates a second event or duplicate webhook deliveries. required: false name: idempotency-key in: header description: |- Specifies idempotency key for this header parameter. **Value constraints** | Constraint | Accepted input | | --- | --- | | Pattern | `^[\x21-\x7e]{1,255}$` | requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/native__TriggerTestEventRequest' responses: '202': description: Test event accepted for delivery content: application/json: schema: $ref: '#/components/schemas/native__TriggerTestEventResponse' '400': description: Invalid fixture, override, or real session content: application/json: schema: $ref: '#/components/schemas/native__PublicError' example: error: type: invalid_request_error code: invalid_parameter message: Correct the invalid request field. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#invalid-parameter '403': description: Test numbers access required, or a client token was used content: application/json: schema: $ref: '#/components/schemas/native__PublicError' example: error: type: permission_error code: permission_denied message: The credential does not have access to this resource. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#permission-denied '404': description: Project or Test number not found content: application/json: schema: $ref: '#/components/schemas/native__PublicError' example: error: type: invalid_request_error code: resource_not_found message: The resource is unavailable to this caller. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#resource-not-found '429': description: Test event rate limit reached content: application/json: schema: $ref: '#/components/schemas/native__PublicError' example: error: type: rate_limit_error code: rate_limit_exceeded message: >- The request limit was reached. Follow Retry-After when supplied. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#rate-limit-exceeded '502': description: >- Test event delivery unavailable. Retry with the same Idempotency-Key to avoid a second event. content: application/json: schema: $ref: '#/components/schemas/native__PublicError' example: error: type: upstream_error code: upstream_failure message: The messaging provider could not complete the request. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#upstream-failure security: - native__BearerAuth: [] servers: - url: https://api.polymorfa.com components: schemas: native__TriggerTestEventRequest: type: object properties: session: type: string minLength: 1 maxLength: 128 description: |- Test number session name in the project. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `128` characters | event: type: string enum: - message.received - message.ack - message.failed - call.received - call.missed - call.ended - session.status - template.status - bansafe.enforcement - bansafe.risk_changed description: |- Fixture name. Each name is the event type it produces. **Allowed values** | Value | Meaning | | --- | --- | | `message.received` | Message.received. | | `message.ack` | Message.ack. | | `message.failed` | Message.failed. | | `call.received` | Call.received. | | `call.missed` | Call.missed. | | `call.ended` | Call.ended. | | `session.status` | Session.status. | | `template.status` | Template.status. | | `bansafe.enforcement` | Bansafe.enforcement. | | `bansafe.risk_changed` | Bansafe.risk changed. | overrides: allOf: - $ref: '#/components/schemas/native__TestEventOverrides' description: Specifies overrides for this native trigger test event request. fromSession: type: string minLength: 1 maxLength: 128 description: >- message.received only. Send a simulated text message from this other connected Test number in the same project instead of generating an event. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `128` characters | required: - session - event additionalProperties: false native__TriggerTestEventResponse: type: object properties: event: type: string enum: - message.received - message.ack - message.failed - call.received - call.missed - call.ended - session.status - template.status - bansafe.enforcement - bansafe.risk_changed description: |- Specifies event for this native trigger test event response. **Allowed values** | Value | Meaning | | --- | --- | | `message.received` | Message.received. | | `message.ack` | Message.ack. | | `message.failed` | Message.failed. | | `call.received` | Call.received. | | `call.missed` | Call.missed. | | `call.ended` | Call.ended. | | `session.status` | Session.status. | | `template.status` | Template.status. | | `bansafe.enforcement` | Bansafe.enforcement. | | `bansafe.risk_changed` | Bansafe.risk changed. | session: type: string description: Identifier of the connected Polymorfa session. delivery: type: string enum: - generated - simulated description: |- Specifies delivery for this native trigger test event response. **Allowed values** | Value | Meaning | | --- | --- | | `generated` | Generated. | | `simulated` | Simulated. | eventId: type: string nullable: true format: uuid description: |- Identifier for the event. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string`; Format: `uuid` | | Alternative 2 | `null` | **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uuid` | source: type: string enum: - test - runtime description: |- Specifies source for this native trigger test event response. **Allowed values** | Value | Meaning | | --- | --- | | `test` | Test. | | `runtime` | Runtime. | required: - event - session - delivery - eventId - source native__PublicError: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - conflict_error - rate_limit_error - api_error - upstream_error description: |- Type discriminator for this object. **Allowed values** | Value | Meaning | | --- | --- | | `invalid_request_error` | Invalid request error. | | `authentication_error` | Authentication error. | | `permission_error` | Permission error. | | `conflict_error` | Conflict error. | | `rate_limit_error` | Rate limit error. | | `api_error` | Api error. | | `upstream_error` | Upstream error. | code: type: string enum: - invalid_parameter - invalid_credential - entitlement_required - method_not_allowed - permission_denied - missing_scope - resource_not_found - media_fetch_failed - resource_gone - feature_unavailable - stream_cursor_invalid - stream_cursor_expired - stream_connection_limit_reached - state_conflict - idempotency_conflict - idempotency_in_progress - idempotency_completed - idempotency_outcome_unknown - call_claimed - call_not_ringing - connection_limit - unsupported_for_connection - call_permission_required - invalid_sip_trunk - calls_disabled - sip_trunk_in_use - sip_trunk_revision_conflict - sip_trunk_limit - sip_unavailable - rate_limit_exceeded - internal_error - operation_not_supported - upstream_failure - service_unavailable - credential_verification_unavailable - session_not_ready - command_dispatch_failed - result_unknown - recipient_not_on_whatsapp - conversation_window_closed - template_not_approved - media_too_large - whatsapp_rate_limited - new_chat_limit_reached - whatsapp_account_restricted - bansafe_suspended - bansafe_org_suspended - bansafe_cold_blocked - bansafe_cold_held - bansafe_throttled - bansafe_daily_allowance_reached - bansafe_accounting_unavailable - bansafe_send_outcome_unknown - campaigns_not_entitled description: >- Stable machine-readable code for this result. **Allowed values** | Value | Meaning | | --- | --- | | `invalid_parameter` | Invalid parameter. | | `invalid_credential` | Invalid credential. | | `entitlement_required` | Entitlement required. | | `method_not_allowed` | Method not allowed. | | `permission_denied` | Permission denied. | | `missing_scope` | Missing scope. | | `resource_not_found` | Resource not found. | | `media_fetch_failed` | Media fetch failed. | | `resource_gone` | Resource gone. | | `feature_unavailable` | Feature unavailable. | | `stream_cursor_invalid` | Stream cursor invalid. | | `stream_cursor_expired` | Stream cursor expired. | | `stream_connection_limit_reached` | Stream connection limit reached. | | `state_conflict` | State conflict. | | `idempotency_conflict` | Idempotency conflict. | | `idempotency_in_progress` | Idempotency in progress. | | `idempotency_completed` | Idempotency completed. | | `idempotency_outcome_unknown` | Idempotency outcome unknown. | | `call_claimed` | Call claimed. | | `call_not_ringing` | Call not ringing. | | `connection_limit` | Connection limit. | | `unsupported_for_connection` | Unsupported for connection. | | `call_permission_required` | Call permission required. | | `invalid_sip_trunk` | Invalid sip trunk. | | `calls_disabled` | Calls disabled. | | `sip_trunk_in_use` | Sip trunk in use. | | `sip_trunk_revision_conflict` | Sip trunk revision conflict. | | `sip_trunk_limit` | Sip trunk limit. | | `sip_unavailable` | Sip unavailable. | | `rate_limit_exceeded` | Rate limit exceeded. | | `internal_error` | Internal error. | | `operation_not_supported` | Operation not supported. | | `upstream_failure` | Upstream failure. | | `service_unavailable` | Service unavailable. | | `credential_verification_unavailable` | Credential verification unavailable. | | `session_not_ready` | Session not ready. | | `command_dispatch_failed` | Command dispatch failed. | | `result_unknown` | Result unknown. | | `recipient_not_on_whatsapp` | Recipient not on whatsapp. | | `conversation_window_closed` | Conversation window closed. | | `template_not_approved` | Template not approved. | | `media_too_large` | Media too large. | | `whatsapp_rate_limited` | Whatsapp rate limited. | | `new_chat_limit_reached` | New chat limit reached. | | `whatsapp_account_restricted` | Whatsapp account restricted. | | `bansafe_suspended` | Bansafe suspended. | | `bansafe_org_suspended` | Bansafe org suspended. | | `bansafe_cold_blocked` | Bansafe cold blocked. | | `bansafe_cold_held` | Bansafe cold held. | | `bansafe_throttled` | Bansafe throttled. | | `bansafe_daily_allowance_reached` | Bansafe daily allowance reached. | | `bansafe_accounting_unavailable` | Bansafe accounting unavailable. | | `bansafe_send_outcome_unknown` | Bansafe send outcome unknown. | | `campaigns_not_entitled` | Campaigns not entitled. | message: type: string description: Human-readable message associated with this result. param: type: string nullable: true description: |- Specifies param for this error. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | request_id: type: string description: >- Matches the X-Request-Id response header. Include it when you contact support. request_log_url: type: string format: uri description: >- Console page that shows this request. Returned only to organization and project credentials whose request was logged. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uri` | required: - type - code - message - param - request_id description: Error details returned when the operation fails. data: type: string nullable: true enum: - null description: |- Always null for a failed request. **Allowed values** | Value | Meaning | | --- | --- | | `null` | Null. | **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | docs: type: string format: uri description: |- Specifies docs for this native public error. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uri` | required: - error - data - docs native__TestEventOverrides: type: object properties: text: type: string minLength: 1 maxLength: 4096 description: |- Text content carried by this object. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `4096` characters | from: type: string pattern: ^\+[1-9]\d{7,14}$ description: >- Stable identifier for the conversation or account that originated the event. **Value constraints** | Constraint | Accepted input | | --- | --- | | Pattern | `^\+[1-9]\d{7,14}$` | pushName: type: string minLength: 1 maxLength: 64 description: |- WhatsApp display name reported by the sender's client. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `64` characters | mediaType: type: string enum: - image - video - audio - document - sticker description: |- Category assigned to media. **Allowed values** | Value | Meaning | | --- | --- | | `image` | Image. | | `video` | Video. | | `audio` | Audio. | | `document` | Document. | | `sticker` | Sticker. | caption: type: string minLength: 1 maxLength: 1024 description: |- Caption shown with the attached media. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `1024` characters | ackStatus: type: string enum: - delivered - read - played - error description: |- Specifies ack status for this native test event override. **Allowed values** | Value | Meaning | | --- | --- | | `delivered` | Delivered. | | `read` | Read. | | `played` | Played. | | `error` | Error. | messageId: type: string pattern: ^[1-9][0-9]{0,18}$ description: |- Polymorfa message ID. Use the message's `id`, not its `whatsapp_id`. **Value constraints** | Constraint | Accepted input | | --- | --- | | Pattern | `^[1-9][0-9]{0,18}$` | failureReason: type: string enum: - invalid_recipient - session_not_connected - ack_timeout - send_failed - blocked_by_safety description: |- Specifies failure reason for this native test event override. **Allowed values** | Value | Meaning | | --- | --- | | `invalid_recipient` | Invalid recipient. | | `session_not_connected` | Session not connected. | | `ack_timeout` | Ack timeout. | | `send_failed` | Send failed. | | `blocked_by_safety` | Blocked by safety. | video: type: boolean description: Whether video. durationSeconds: type: integer minimum: 0 maximum: 86400 description: |- Duration in seconds. **Value constraints** | Constraint | Accepted input | | --- | --- | | Numeric value | `0` through `86400` (inclusive) | callEndReason: type: string enum: - user_hangup - timeout - lost_connection - rejected description: |- Specifies call end reason for this native test event override. **Allowed values** | Value | Meaning | | --- | --- | | `user_hangup` | User hangup. | | `timeout` | Timeout. | | `lost_connection` | Lost connection. | | `rejected` | Rejected. | status: type: string enum: - CONNECTING - CONNECTED - DISCONNECTED description: |- Current status of this resource or operation. **Allowed values** | Value | Meaning | | --- | --- | | `CONNECTING` | Connecting. | | `CONNECTED` | Connected. | | `DISCONNECTED` | Disconnected. | statusReason: type: string enum: - SCAN_QR - AUTO_RECONNECT - FAILED - MANUAL_STOP - QR_TIMEOUT - LOGGED_OUT - TEMPORARY_BAN - STREAM_ERROR description: |- Reason for the current status. **Allowed values** | Value | Meaning | | --- | --- | | `SCAN_QR` | Scan qr. | | `AUTO_RECONNECT` | Auto reconnect. | | `FAILED` | Failed. | | `MANUAL_STOP` | Manual stop. | | `QR_TIMEOUT` | Qr timeout. | | `LOGGED_OUT` | Logged out. | | `TEMPORARY_BAN` | Temporary ban. | | `STREAM_ERROR` | Stream error. | templateName: type: string pattern: ^[a-z0-9_]{1,512}$ description: |- Human-readable template name for this native test event override. **Value constraints** | Constraint | Accepted input | | --- | --- | | Pattern | `^[a-z0-9_]{1,512}$` | templateStatus: type: string enum: - APPROVED - REJECTED description: |- Specifies template status for this native test event override. **Allowed values** | Value | Meaning | | --- | --- | | `APPROVED` | Approved. | | `REJECTED` | Rejected. | reason: type: string minLength: 1 maxLength: 256 description: |- Reason for the reported state or outcome. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `256` characters | enforcementKind: type: string enum: - cap_warning - cap_reached - timelock - temporary_ban description: |- Category assigned to enforcement. **Allowed values** | Value | Meaning | | --- | --- | | `cap_warning` | Cap warning. | | `cap_reached` | Cap reached. | | `timelock` | Timelock. | | `temporary_ban` | Temporary ban. | riskLevel: type: string enum: - low - elevated - high - critical description: |- Specifies risk level for this native test event override. **Allowed values** | Value | Meaning | | --- | --- | | `low` | Low. | | `elevated` | Elevated. | | `high` | High. | | `critical` | Critical. | additionalProperties: false securitySchemes: native__BearerAuth: type: http scheme: bearer description: >- Polymorfa organization key (pmfa_ prefix), project token (pmfa_pt_ prefix) where supported, or short-lived client token (pmfa_ct_ prefix). Organization and project keys may be personal or service-account owned and enforce selected action scopes. Organization keys cover the team and its projects; project tokens stay inside one project. Client tokens stay inside their live project and session and enforce their client rules. ````