Skip to main content
PUT
/
instances
/
{instanceId}
/
token
/
{token}
/
update-filters
Webhook Filters
curl --request PUT \
  --url https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters \
  --header 'Client-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "messageFilters": {},
  "callbackTypeFilters": {}
}
'

​
Overview

The filters endpoint allows you to configure which events and message types will be triggered by your instance’s webhooks. You can:
  • Filter message types received in the On message received webhook (e.g., ignore group messages or audio-only messages)
  • Filter webhook types that will be triggered (e.g., disable the Chat presence webhook without removing the configured URL)
The same settings can also be configured directly from the instance panel, using toggles on each webhook.
The messageFilters filters apply only to the On message received webhook. Other webhooks are not affected by this filter.

​
Update filters

​
instanceId
string
required
Your instance ID. Available in the Z-API panel under Instances.
​
token
string
required
Your Z-API instance token.

​
Body

​
messageFilters
array of strings
List of message type filters. Types included in the array will not be delivered to the On message received webhook (ReceivedCallback). See the possible values below.
​
callbackTypeFilters
array of strings
List of webhook type filters. Webhooks included in the array will not be triggered, even if they have a configured URL. See the possible values below.

​
Request Body

{
  "messageFilters": [
    "FILTER_FROM_GROUP",
    "FILTER_FROM_PRIVATE_CHAT",
    "FILTER_TEXT_MESSAGE",
    "FILTER_IMAGE_MESSAGE",
    "FILTER_VIDEO_MESSAGE",
    "FILTER_AUDIO_MESSAGE",
    "FILTER_DOCUMENT_MESSAGE"
  ],
  "callbackTypeFilters": [
    "FILTER_DELIVERY_CALLBACK",
    "FILTER_DISCONNECTED_CALLBACK",
    "FILTER_RECEIVED_CALLBACK",
    "FILTER_PRESENCE_CHAT_CALLBACK",
    "FILTER_MESSAGE_STATUS_CALLBACK",
    "FILTER_CONNECTED_CALLBACK"
  ]
}

​
Filter types for webhooks

​
Filters by message type

These apply to the On message received webhook (ReceivedCallback). Messages whose type is included in the messageFilters array will not be delivered.
Filters messages received in groups. When active, no messages received in a group will be delivered to the ReceivedCallback.
Filters messages received in private chats. When active, only group messages will be delivered to the ReceivedCallback.
Filters plain text messages.
Filters image messages.
Filters video messages.
Filters audio messages.
Filters document messages.

​
Filters by webhook type

These apply to webhooks in general. Webhooks whose type is included in the callbackTypeFilters array will not be triggered, regardless of whether they have a configured URL.
Disables the On message received (ReceivedCallback)
Disables the On message send (DeliveryCallback)
Disables the On connected (ConnectedCallback)
Disables the On disconnected (DisconnectedCallback)
Disables the Chat presence (PresenceChatCallback)
Disables the Message status (MessageStatusCallback)

​
Response

​
200

{
  "value": true
}

​
405

In this case, make sure you are correctly specifying the request method. Check that you sent a PUT request as indicated at the top of this page.

​
415

If you receive a 415 error, make sure to add the “Content-Type” header to your request with the type of object you are sending, in most cases “application/json”.