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": {}
}
'

import requests

url = "https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters"

payload = {
    "messageFilters": {},
    "callbackTypeFilters": {}
}
headers = {
    "Client-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Client-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({messageFilters: {}, callbackTypeFilters: {}})
};

fetch('https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'messageFilters' => [
        
    ],
    'callbackTypeFilters' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Client-Token: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters"

	payload := strings.NewReader("{\n  \"messageFilters\": {},\n  \"callbackTypeFilters\": {}\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Client-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters")
  .header("Client-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messageFilters\": {},\n  \"callbackTypeFilters\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Client-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messageFilters\": {},\n  \"callbackTypeFilters\": {}\n}"

response = http.request(request)
puts response.read_body

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": {}
}
'

import requests

url = "https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters"

payload = {
    "messageFilters": {},
    "callbackTypeFilters": {}
}
headers = {
    "Client-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {'Client-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({messageFilters: {}, callbackTypeFilters: {}})
};

fetch('https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'messageFilters' => [
        
    ],
    'callbackTypeFilters' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Client-Token: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters"

	payload := strings.NewReader("{\n  \"messageFilters\": {},\n  \"callbackTypeFilters\": {}\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Client-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters")
  .header("Client-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"messageFilters\": {},\n  \"callbackTypeFilters\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.z-api.io/instances/{instanceId}/token/{token}/update-filters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Client-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messageFilters\": {},\n  \"callbackTypeFilters\": {}\n}"

response = http.request(request)
puts response.read_body

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

string

required

Your instance ID. Available in the Z-API panel under Instances.

string

required

Your Z-API instance token.

Body

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.

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.

FILTER_FROM_GROUP

Filters messages received in groups. When active, no messages received in a group will be delivered to the ReceivedCallback.

FILTER_FROM_PRIVATE_CHAT

Filters messages received in private chats. When active, only group messages will be delivered to the ReceivedCallback.

FILTER_TEXT_MESSAGE

Filters plain text messages.

FILTER_IMAGE_MESSAGE

Filters image messages.

FILTER_VIDEO_MESSAGE

Filters video messages.

FILTER_AUDIO_MESSAGE

Filters audio messages.

FILTER_DOCUMENT_MESSAGE

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.

FILTER_RECEIVED_CALLBACK

Disables the On message received (ReceivedCallback)

FILTER_DELIVERY_CALLBACK

Disables the On message send (DeliveryCallback)

FILTER_CONNECTED_CALLBACK

Disables the On connected (ConnectedCallback)

FILTER_DISCONNECTED_CALLBACK

Disables the On disconnected (DisconnectedCallback)

FILTER_PRESENCE_CHAT_CALLBACK

Disables the Chat presence (PresenceChatCallback)

FILTER_MESSAGE_STATUS_CALLBACK

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”.

​Overview

​Update filters

​Header

​Body

​Request Body

​Filter types for webhooks

​Filters by message type

​Filters by webhook type

​Response

​200

​405

​415

Overview

Update filters

Header

Body

Request Body

Filter types for webhooks

Filters by message type

Filters by webhook type

Response

200

405

415