PingOne Platform APIs

Instant Messaging Delivery Settings

Use the /instantMessagingDeliverySettings/whatsApp endpoint to configure the sending of PingOne notifications via WhatsApp.

WhatsApp delivery settings data model

Property Type Required Mutable Description

appId

String

Required

Mutable

The ID of the WhatsApp app you are using for sending the notifications.

appSecret

String

Required

Mutable

The secret for the WhatsApp app you are using for sending the notifications.

createdAt

Date

N/A

Read-only

Date and time that the delivery settings were created.

environment.id

String

N/A

Read-only

The ID of the PingOne environment.

id

String

N/A

Read-only

The ID assigned to the delivery settings.

numbers[]

Array

Optional

Mutable

The numbers array is included in the response when creating WhatsApp settings. It contains information about the various phone numbers available for use with the app ID that was specified in the creation request. If there is more than one number available for the app, a second PUT request can be run to specify the number to use for sending notifications. To specify the number to use, include the numbers array in your request, set numbers[].selected to true, and specify the number ID with numbers[].numberId or the number itself with numbers[].number.

numbers[].available

Boolean

N/A

Read-only

Specifies whether the number is currently available in the account.

numbers[].capabilities

Array

N/A

Read-only

For WhatsApmp settings, will always consist of a single element, WHATSAPP.

numbers[].createdAt

Date

N/A

Read-only

The time the resource was created.

numbers[].number

String

Required

Mutable

The number for sending notifications.

numbers[].numberId

String

Required

Mutable

The ID of the number for sending notifications.

numbers[].qualityRating

String

N/A

Read-only

The current WhatsApp quality rating for the number.

numbers[].selected

Boolean

Required

Mutable

Set to true when specifying a specific number to use for sending notifications.

numbers[].type

String

N/A

Read-only

For WhatsApp settings, the value returned is WHATSAPP.

numbers[].verifiedName

String

N/A

Read-only

The verified name for the number.

provider

String

Required

Mutable

For configuring WhatsApp settings, set the value to CUSTOM_WHATSAPP.

userAccessToken

String

Required

Mutable

The access token for the WhatsApp business account.

whatsAppAccountBusinessId

String

Required

Mutable

The ID of the WhatsApp business account.

status

String

N/A

Read-only

The status of the creation of the delivery settings. In the response to the create request, the value is Pending. Status changes to Created after the configuration has been completed.

type

String

N/A

Read-only

For WhatsApp settings, the value returned is WHATSAPP.

updatedAt

Date

N/A

Read-only

Date and time that the delivery settings were last updated.

whatsAppTemplate

Object

N/A

Read-only

Included in the response if you included expand=whatsAppTemplates as a query parameter when getting the WhatsApp delivery settings. Refer to the Read WhatsApp Delivery Settings (including templates) example.

whatsAppTemplate.category

String

N/A

Read-only

The category of the template. Currently will always be AUTHENTICATION.

whatsAppTemplate.id

String

N/A

Read-only

The WhatsApp-provided ID of the template.

whatsAppTemplate.language

String

N/A

Read-only

The language of the template.

whatsAppTemplate.name

String

N/A

Read-only

The name of the template.

Instant messaging delivery settings errors

In addition to the general error codes, instant messaging delivery settings operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [<field> <message>] (for example, Validation Error : [whatsAppAccountBusinessId must not be blank])

When and details

When: A create or update request body fails constraint validation (for example, the request omits whatsAppAccountBusinessId or appId).

Details: Detail EMPTY_VALUE with target = the field path and message = the constraint message. Only whatsAppAccountBusinessId and appId carry NotNull/NotBlank constraints.

400

INVALID_DATA

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A request body is malformed JSON or contains a value of the wrong type (for example, a non-UUID instantMessagingDeliverySettingsId).

Details: For JSON deserialization failures, detail INVALID_VALUE with target = the JSON path of the failing property and message Invalid value for attribute.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A create request omits userAccessToken, or the request body specifies a provider other than CUSTOM_WHATSAPP on the WhatsApp endpoints.

Details: Detail INVALID_VALUE with the reason: Provider Credentials Secret should not be null (an omitted userAccessToken; WhatsApp maps userAccessToken to the provider credentials secret) or Invalid provider for WhatsApp settings.

400

INVALID_DATA

REQUIRED_VALUE

Message: The request is missing a required value.

When and details

When: A create or update request fails to retrieve the phone numbers from the WhatsApp business account (the WhatsApp API rejects the account ID or access token).

Details: Detail REQUIRED_VALUE with the WhatsApp API error, for example Get WhatsApp numbers failed. whatsAppNumbersResponse:<response>.

201 (no error)

None

None

Message: None. No error response is returned; read the settings to observe the failure.

When and details

When: A create request completes but the asynchronous WhatsApp webhook creation fails (the app ID or app secret is rejected by WhatsApp). The create response itself succeeds; the asynchronous task then stores the resource with status of Failed and a failureReason of WhatsApp webhook creation failed or WhatsApp webhook creation retry failed.

Details: None.

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A GET Read WhatsApp Delivery Settings (including templates) request fails to retrieve the WhatsApp message templates (the WhatsApp API rejects the request).

Details: Detail INVALID_VALUE with message Get WhatsApp message templates. messageTemplatesResponse:<response>.

400

REQUEST_LIMITED

LIMIT_EXCEEDED

Message: The request exceeded the allowed rate limit.

When and details

When: A create request exceeds the maximum of 10 instant messaging delivery settings per environment.

Details: Detail LIMIT_EXCEEDED with message Maximum allowed InstantMessagingDeliverySettings limit has been reached, limit=10.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the permission for the operation: notifications:update:notificationsSettings (create and update operations), notifications:read:notificationsSettings (GET operations), or notifications:delete:notificationsSettings (DELETE operations).

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A request specifies an environment that does not exist.

Details: None.

404

NOT_FOUND

INVALID_VALUE

Message: The request could not be completed. The requested resource was not found.

When and details

When: A request specifies an instantMessagingDeliverySettingsId that does not exist in the environment.

Details: Detail INVALID_VALUE with message InstantMessagingDeliverySettings resource not found, id=<id>.