Requesting a Capability Query for a contact. See the API reference and callbacks page for more information.
A Capability Query means checking the available options to reach the contact on the channels where it has a channel identity.
Capability Queries can only be executed for contacts that already exist in a project/app. For executing the request, it's required to provide either the contactId or the channel recipient identities of the contact.
The request is executed asynchronously, therefore the service responds immediately. The result of the Capability Query is sent to the registered webhook for the CAPABILITY trigger. To set up webhooks with the proper trigger read about webhooks.
Below you can find an example for executing a Capability Query request using a list of channel recipient identities.
Conversation API POST capability:query
{
"app_id": "{{APP_ID}}",
"project_id": "{{PROJECT_ID}}",
"recipient": {
"identified_by": {
"channel_identities": [
{
"channel": "WHATSAPP",
"identity": "{{WHATSAPP_IDENTITY}}"
}
]
}
}
}Alternatively, you can create a contact beforehand or use an existing contact's ID.
{
"app_id": "{{APP_ID}}",
"project_id": "{{PROJECT_ID}}",
"recipient": {
"contact_id": "{{CONTACT_ID}}"
}
}The response for the Capability Query is the registered request. The result of the query is returned through the webhook with CAPABILITY trigger, see Capability Notification.
The result of a Capability Query is posted to the webhook which has CAPABILITY trigger set.
Below you can find an example for Capability Notification.
{
"contact_id": "{{CONTACT_ID}}",
"identity": "{{WHATSAPP_IDENTITY}}",
"channel": "WHATSAPP",
"capability_status": "CAPABILITY_FULL"
}The Capability Notification can have the following fields:
| Field | Description |
|---|---|
contact_id | The id of the contact that the query was executed for. |
identity | The channel recipient identity of the contact. |
channel | The channel that the capability information was retrieved from. |
capability_status | The capability of the contact reported by the channel. See possible values below the table. |
reason | If the capability query failed the reason is present in this field. |
channel_capabilities | If the underlying channel has a list of specific capabilities then it's listed here. |
Possible values for capability_status are:
CAPABILITY_UNKNOWN: the channel capability for the contact is unknown due to the underlying channel not making this information available.CAPABILITY_FULL: the specified contact supports all the features of the channel.CAPABILITY_PARTIAL: the specified contact supports a subset of the channel features.NO_CAPABILITY: the specified contact has no capability on the channel.