Phone Numbers

Check phone health

Health check via Meta APIs and Kapso services.

Results are cached for 3 minutes per phone number, so repeated calls can return the same payload. Use timestamp to tell when the check actually ran. The cache is invalidated early when the number’s configuration changes.

If a fresh check is already running for the same number and does not finish within 15 seconds, the response is status: error with an error message asking you to retry shortly.

When a check keeps failing to read the phone number from Meta because of an access or token error, the result is held for longer: 5, then 15, then 30, then 60 minutes. During that window the response repeats the last payload and adds retry_after. Rate limits, payment errors and transport failures do not trigger this. A successful check clears retry_after and resets the delay, as does reconnecting the number or changing its credentials.

When Meta reports the number as DISCONNECTED, the overall status is unhealthy even if the other checks pass. Reconnect the number to restore messaging. A missing or unrecognized connection status is reported as UNKNOWN and does not affect the overall status.

Health checks are limited to 5 requests per second and 60 requests per minute per project, shared across all API keys in the project. Over the limit the request is rejected with 429 before Meta is called, and Retry-After tells you how many seconds to wait. Every response carries the current counters in the X-Health-RateLimit-* headers.

GET

phone_numbers

{phone_number_id}

health

Check phone health

curl --request GET \
  --url https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health', 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.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health")

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

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

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

{
  "status": "healthy",
  "timestamp": "2025-01-20T14:25:30Z",
  "checks": {
    "phone_number_access": {
      "passed": true,
      "details": {
        "verified_name": "My Business",
        "display_phone_number": "+1 555-123-4567",
        "quality_rating": "GREEN",
        "status": "CONNECTED",
        "throughput_tier": "TIER_10K",
        "id": "123456789012345"
      }
    },
    "phone_number_connection": {
      "passed": true,
      "details": {
        "status": "CONNECTED"
      }
    },
    "messaging_health": {
      "passed": true,
      "overall_status": "AVAILABLE",
      "details": {
        "can_send_message": "AVAILABLE",
        "entities": [
          {
            "entity_type": "PHONE_NUMBER",
            "id": "123456789012345",
            "can_send_message": "AVAILABLE"
          },
          {
            "entity_type": "WABA",
            "id": "987654321098765",
            "can_send_message": "AVAILABLE"
          },
          {
            "entity_type": "BUSINESS",
            "id": "456789012345678",
            "can_send_message": "AVAILABLE"
          },
          {
            "entity_type": "APP",
            "id": "789012345678901",
            "can_send_message": "AVAILABLE"
          }
        ]
      }
    },
    "webhook_subscription": {
      "passed": true,
      "details": {
        "app_id": "789012345678901",
        "subscribed": true,
        "subscribed_fields": [
          "messages",
          "message_template_status_update"
        ]
      }
    },
    "webhook_verified": {
      "passed": true,
      "details": {
        "verified_at": "2025-01-15T10:30:00Z",
        "message": "Webhook successfully verified at 2025-01-15 10:30:00 UTC"
      }
    }
  }
}

Authorizations

X-API-Key

string

header

required

Path Parameters

phone_number_id

string

required

Response

Health status

status

enum<string>

required

Available options:

healthy,

degraded,

unhealthy,

error

timestamp

string<date-time>

required

retry_after

string<date-time>

Present only while the number is in access-error backoff. The earliest time a later request will re-check Meta. Requests made before this time return this same cached payload. It is not a scheduled re-check or a guarantee that the next check will succeed.

error

string | null

checks

object | null

Individual check results. Typical checks:

phone_number_access: Meta API connectivity
phone_number_connection: Meta connection status (CONNECTED/DISCONNECTED/UNKNOWN). passed is null when the status is UNKNOWN
messaging_health: Send/receive capability (AVAILABLE/LIMITED/BLOCKED)
webhook_subscription: WABA app subscription status
webhook_verified: Webhook verification status
token_validity: Access token validity (coexistence only)

Show child attributes

Check phone health

curl --request GET \
  --url https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health', 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.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/health")

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

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

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

{
  "status": "healthy",
  "timestamp": "2025-01-20T14:25:30Z",
  "checks": {
    "phone_number_access": {
      "passed": true,
      "details": {
        "verified_name": "My Business",
        "display_phone_number": "+1 555-123-4567",
        "quality_rating": "GREEN",
        "status": "CONNECTED",
        "throughput_tier": "TIER_10K",
        "id": "123456789012345"
      }
    },
    "phone_number_connection": {
      "passed": true,
      "details": {
        "status": "CONNECTED"
      }
    },
    "messaging_health": {
      "passed": true,
      "overall_status": "AVAILABLE",
      "details": {
        "can_send_message": "AVAILABLE",
        "entities": [
          {
            "entity_type": "PHONE_NUMBER",
            "id": "123456789012345",
            "can_send_message": "AVAILABLE"
          },
          {
            "entity_type": "WABA",
            "id": "987654321098765",
            "can_send_message": "AVAILABLE"
          },
          {
            "entity_type": "BUSINESS",
            "id": "456789012345678",
            "can_send_message": "AVAILABLE"
          },
          {
            "entity_type": "APP",
            "id": "789012345678901",
            "can_send_message": "AVAILABLE"
          }
        ]
      }
    },
    "webhook_subscription": {
      "passed": true,
      "details": {
        "app_id": "789012345678901",
        "subscribed": true,
        "subscribed_fields": [
          "messages",
          "message_template_status_update"
        ]
      }
    },
    "webhook_verified": {
      "passed": true,
      "details": {
        "verified_at": "2025-01-15T10:30:00Z",
        "message": "Webhook successfully verified at 2025-01-15 10:30:00 UTC"
      }
    }
  }
}

Overview

WhatsApp API

Platform API

Workflows API

Kapso Agent API

Check phone health

Authorizations

Path Parameters

Response