Connect a WhatsApp number

Connect a number with a token from your own Meta app (WhatsApp > API Setup): its phone number id, its WhatsApp Business Account id, a permanent access token and the app secret. The number is checked with Meta, and your app is subscribed to its webhooks.

The response carries webhook.url and a verify_token, shown once: enter both in your Meta app under WhatsApp > Configuration and subscribe to the messages field. Set inbound_agent_id to have an agent answer the number.

In the console, Connect WhatsApp opens Meta’s own sign-up instead, with no app of your own needed. Connecting a number you already connected updates it (200). Requires whatsapp:write.

POST

accounts

Connect a WhatsApp number

curl --request POST \
  --url https://api.voice.wixzel.com/v1/whatsapp/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "access_token": "<string>",
  "phone_number_id": "<string>",
  "waba_id": "<string>",
  "app_secret": "<string>",
  "name": "<string>",
  "inbound_agent_id": "6a96a3ead6e886d42462dd3e"
}
'

import requests

url = "https://api.voice.wixzel.com/v1/whatsapp/accounts"

payload = {
    "access_token": "<string>",
    "phone_number_id": "<string>",
    "waba_id": "<string>",
    "app_secret": "<string>",
    "name": "<string>",
    "inbound_agent_id": "6a96a3ead6e886d42462dd3e"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    access_token: '<string>',
    phone_number_id: '<string>',
    waba_id: '<string>',
    app_secret: '<string>',
    name: '<string>',
    inbound_agent_id: '6a96a3ead6e886d42462dd3e'
  })
};

fetch('https://api.voice.wixzel.com/v1/whatsapp/accounts', 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.voice.wixzel.com/v1/whatsapp/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'access_token' => '<string>',
    'phone_number_id' => '<string>',
    'waba_id' => '<string>',
    'app_secret' => '<string>',
    'name' => '<string>',
    'inbound_agent_id' => '6a96a3ead6e886d42462dd3e'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.voice.wixzel.com/v1/whatsapp/accounts"

	payload := strings.NewReader("{\n  \"access_token\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"waba_id\": \"<string>\",\n  \"app_secret\": \"<string>\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.post("https://api.voice.wixzel.com/v1/whatsapp/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access_token\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"waba_id\": \"<string>\",\n  \"app_secret\": \"<string>\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.voice.wixzel.com/v1/whatsapp/accounts")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access_token\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"waba_id\": \"<string>\",\n  \"app_secret\": \"<string>\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}"

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

{
  "id": "6a96a3ead6e886d42462dd3e",
  "object": "whatsapp_account",
  "name": "<string>",
  "display_phone_number": "+91 98765 43210",
  "verified_name": "<string>",
  "phone_number_id": "<string>",
  "waba_id": "<string>",
  "quality_rating": "GREEN",
  "messaging_limit_tier": "TIER_1K",
  "connection": "embedded_signup",
  "coexistence": true,
  "status": "connected",
  "last_error": "<string>",
  "webhook": {
    "status": "pending",
    "last_received_at": "2026-09-01T12:00:00.000Z",
    "url": "<string>"
  },
  "inbound_agent_id": "6a96a3ead6e886d42462dd3e",
  "settings": {
    "messaging_enabled": true,
    "voice_note_replies": true,
    "typing_indicator": true,
    "inactivity_minutes": 15,
    "offline_reply": "<string>",
    "human_pause_minutes": 720
  },
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "verify_token": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Your Wixzel Voice API key: Authorization: Bearer wv_live_.... Keys are scoped; grant only what the integration needs.

Body

application/json

access_token

string

required

A permanent access token from your Meta app (a system user token) with whatsapp_business_messaging and whatsapp_business_management.

Required string length: 20 - 1000

phone_number_id

string

required

Pattern: ^\d{5,30}$

waba_id

string

required

Pattern: ^\d{5,30}$

app_secret

string

required

Your Meta app’s secret, from App settings > Basic. Used only to check that webhooks really come from Meta.

Required string length: 16 - 200

name

string

Maximum string length: 100

inbound_agent_id

string | null

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

Response

The connected number, with its webhook settings

string

required

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

object

enum<string>

required

Available options:

whatsapp_account

name

string

required

display_phone_number

string

required

Example:

"+91 98765 43210"

verified_name

string

required

The business name WhatsApp shows.

phone_number_id

string

required

Meta’s id for the number.

waba_id

string

required

Meta’s id for the WhatsApp Business Account the number belongs to.

quality_rating

string

required

GREEN, YELLOW, RED or UNKNOWN, as Meta rates the number.

Example:

"GREEN"

messaging_limit_tier

string | null

required

How many people the number may start conversations with per day.

Example:

"TIER_1K"

connection

enum<string>

required

embedded_signup when connected in the console with Meta’s sign-up; manual when connected with your own Meta app’s token.

Available options:

embedded_signup,

manual

coexistence

boolean

required

The number also stays on the WhatsApp Business app.

status

enum<string>

required

Available options:

connected,

error,

disconnected

last_error

string | null

required

webhook

object

required

Show child attributes

inbound_agent_id

string | null

required

The agent that answers this number’s chats. With none, messages are stored and not answered.

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

settings

object

required

Show child attributes

created_at

string<date-time>

required

ISO 8601, always UTC.

Example:

"2026-09-01T12:00:00.000Z"

updated_at

string<date-time>

required

ISO 8601, always UTC.

Example:

"2026-09-01T12:00:00.000Z"

verify_token

string

required

Shown once. Enter it with webhook.url in your Meta app’s WhatsApp webhook settings, and subscribe to the messages field. Empty when the number is in Wixzel Voice’s own Meta app, whose webhook is already set.

Connect a WhatsApp number

curl --request POST \
  --url https://api.voice.wixzel.com/v1/whatsapp/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "access_token": "<string>",
  "phone_number_id": "<string>",
  "waba_id": "<string>",
  "app_secret": "<string>",
  "name": "<string>",
  "inbound_agent_id": "6a96a3ead6e886d42462dd3e"
}
'

import requests

url = "https://api.voice.wixzel.com/v1/whatsapp/accounts"

payload = {
    "access_token": "<string>",
    "phone_number_id": "<string>",
    "waba_id": "<string>",
    "app_secret": "<string>",
    "name": "<string>",
    "inbound_agent_id": "6a96a3ead6e886d42462dd3e"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    access_token: '<string>',
    phone_number_id: '<string>',
    waba_id: '<string>',
    app_secret: '<string>',
    name: '<string>',
    inbound_agent_id: '6a96a3ead6e886d42462dd3e'
  })
};

fetch('https://api.voice.wixzel.com/v1/whatsapp/accounts', 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.voice.wixzel.com/v1/whatsapp/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'access_token' => '<string>',
    'phone_number_id' => '<string>',
    'waba_id' => '<string>',
    'app_secret' => '<string>',
    'name' => '<string>',
    'inbound_agent_id' => '6a96a3ead6e886d42462dd3e'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.voice.wixzel.com/v1/whatsapp/accounts"

	payload := strings.NewReader("{\n  \"access_token\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"waba_id\": \"<string>\",\n  \"app_secret\": \"<string>\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.post("https://api.voice.wixzel.com/v1/whatsapp/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access_token\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"waba_id\": \"<string>\",\n  \"app_secret\": \"<string>\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.voice.wixzel.com/v1/whatsapp/accounts")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access_token\": \"<string>\",\n  \"phone_number_id\": \"<string>\",\n  \"waba_id\": \"<string>\",\n  \"app_secret\": \"<string>\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}"

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

{
  "id": "6a96a3ead6e886d42462dd3e",
  "object": "whatsapp_account",
  "name": "<string>",
  "display_phone_number": "+91 98765 43210",
  "verified_name": "<string>",
  "phone_number_id": "<string>",
  "waba_id": "<string>",
  "quality_rating": "GREEN",
  "messaging_limit_tier": "TIER_1K",
  "connection": "embedded_signup",
  "coexistence": true,
  "status": "connected",
  "last_error": "<string>",
  "webhook": {
    "status": "pending",
    "last_received_at": "2026-09-01T12:00:00.000Z",
    "url": "<string>"
  },
  "inbound_agent_id": "6a96a3ead6e886d42462dd3e",
  "settings": {
    "messaging_enabled": true,
    "voice_note_replies": true,
    "typing_indicator": true,
    "inactivity_minutes": 15,
    "offline_reply": "<string>",
    "human_pause_minutes": 720
  },
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "verify_token": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

Getting started

Guides

Carriers

Concepts

API reference

Connect a WhatsApp number

Authorizations

Body

Response