Connect WhatsApp Business

curl --request POST \
  --url https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "code": "<string>",
  "phoneNumberId": "<string>",
  "wabaId": "<string>"
}
'

import requests

url = "https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers"

payload = {
    "code": "<string>",
    "phoneNumberId": "<string>",
    "wabaId": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({code: '<string>', phoneNumberId: '<string>', wabaId: '<string>'})
};

fetch('https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers', 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.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers",
  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([
    'code' => '<string>',
    'phoneNumberId' => '<string>',
    'wabaId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers"

	payload := strings.NewReader("{\n  \"code\": \"<string>\",\n  \"phoneNumberId\": \"<string>\",\n  \"wabaId\": \"<string>\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"<string>\",\n  \"phoneNumberId\": \"<string>\",\n  \"wabaId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"code\": \"<string>\",\n  \"phoneNumberId\": \"<string>\",\n  \"wabaId\": \"<string>\"\n}"

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

{
  "cancellable": true,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "operationId": "<string>",
  "projectId": "<string>",
  "resourceType": "<string>",
  "state": "pending",
  "type": "resource.provision",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "detail": {},
  "endedAt": "2026-01-01T00:00:00.000Z",
  "error": {
    "code": "<string>",
    "detail": "<string>"
  },
  "reason": "charge_refused",
  "resourceId": "<string>",
  "startedAt": "2026-01-01T00:00:00.000Z"
}

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "status": 400,
  "title": "Idempotency Key Required",
  "type": "https://photon.codes/docs/problems/idempotency-key-required"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "ENTITLEMENT_REQUIRED",
  "reason": "card_required",
  "status": 402,
  "title": "Entitlement Required",
  "type": "https://photon.codes/docs/problems/entitlement-required"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "PROJECT_CLOSING",
  "status": 409,
  "title": "Project Is Closing",
  "type": "https://photon.codes/docs/problems/project-closing"
}

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "code": "invalid_type",
      "location": "json",
      "message": "Expected a string.",
      "path": "/name"
    }
  ],
  "status": 422,
  "title": "Request Validation Failed",
  "type": "https://photon.codes/docs/problems/validation-failed"
}

{
  "code": "RATE_LIMITED",
  "status": 429,
  "title": "Too Many Requests",
  "type": "https://photon.codes/docs/problems/rate-limited"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "BILLING_ENTITLEMENTS_PENDING",
  "status": 503,
  "title": "Billing Entitlements Pending",
  "type": "https://photon.codes/docs/problems/billing-entitlements-pending"
}

{
  "code": "REQUEST_TIMEOUT",
  "status": 504,
  "title": "Request Timeout",
  "type": "https://photon.codes/docs/problems/request-timeout"
}

WhatsApp Business

Connect WhatsApp Business

Exchanges the authorization code Embedded Signup returned and connects exactly the selected phone number as one whatsapp_sender. Send the WABA id and phone-number id emitted by the same popup attempt; both are treated as selectors and verified against Meta before use. A selected number that matches a non-retired, same-project voip_line is linked to it; a number absent from Photon inventory stays unbound; a matching non-retired cosmos_line, foreign VoIP line or unassigned VoIP line fails the operation before registration. Connecting is free — no plan requirement — but Billing must report the project’s organization as ready with a payment method on file. The Idempotency-Key is required and permanent: replaying the same key returns the original operation forever. Requires the platforms:write permission bound to the project resource in the path.

POST

projects

{id}

platforms

whatsapp-business

numbers

Connect WhatsApp Business

curl --request POST \
  --url https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "code": "<string>",
  "phoneNumberId": "<string>",
  "wabaId": "<string>"
}
'

import requests

url = "https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers"

payload = {
    "code": "<string>",
    "phoneNumberId": "<string>",
    "wabaId": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({code: '<string>', phoneNumberId: '<string>', wabaId: '<string>'})
};

fetch('https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers', 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.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers",
  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([
    'code' => '<string>',
    'phoneNumberId' => '<string>',
    'wabaId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers"

	payload := strings.NewReader("{\n  \"code\": \"<string>\",\n  \"phoneNumberId\": \"<string>\",\n  \"wabaId\": \"<string>\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"<string>\",\n  \"phoneNumberId\": \"<string>\",\n  \"wabaId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/projects/{id}/platforms/whatsapp-business/numbers")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"code\": \"<string>\",\n  \"phoneNumberId\": \"<string>\",\n  \"wabaId\": \"<string>\"\n}"

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

{
  "cancellable": true,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "operationId": "<string>",
  "projectId": "<string>",
  "resourceType": "<string>",
  "state": "pending",
  "type": "resource.provision",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "detail": {},
  "endedAt": "2026-01-01T00:00:00.000Z",
  "error": {
    "code": "<string>",
    "detail": "<string>"
  },
  "reason": "charge_refused",
  "resourceId": "<string>",
  "startedAt": "2026-01-01T00:00:00.000Z"
}

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "status": 400,
  "title": "Idempotency Key Required",
  "type": "https://photon.codes/docs/problems/idempotency-key-required"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "ENTITLEMENT_REQUIRED",
  "reason": "card_required",
  "status": 402,
  "title": "Entitlement Required",
  "type": "https://photon.codes/docs/problems/entitlement-required"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "PROJECT_CLOSING",
  "status": 409,
  "title": "Project Is Closing",
  "type": "https://photon.codes/docs/problems/project-closing"
}

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "code": "invalid_type",
      "location": "json",
      "message": "Expected a string.",
      "path": "/name"
    }
  ],
  "status": 422,
  "title": "Request Validation Failed",
  "type": "https://photon.codes/docs/problems/validation-failed"
}

{
  "code": "RATE_LIMITED",
  "status": 429,
  "title": "Too Many Requests",
  "type": "https://photon.codes/docs/problems/rate-limited"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "BILLING_ENTITLEMENTS_PENDING",
  "status": 503,
  "title": "Billing Entitlements Pending",
  "type": "https://photon.codes/docs/problems/billing-entitlements-pending"
}

{
  "code": "REQUEST_TIMEOUT",
  "status": 504,
  "title": "Request Timeout",
  "type": "https://photon.codes/docs/problems/request-timeout"
}

Authorizations

Authorization

string

header

required

Account Service Key, prefixed with pho_ask_, sent as Authorization: Bearer <key>. Acts on behalf of its owning account, subject to the permissions and credential restrictions of each operation. Account access tokens and OAuth grants also use the Bearer header. In organizations that require SSO, Account Service Keys are not accepted for managing the organization's SSO settings, deleting the organization, or checking whether it can be deleted.

Headers

Idempotency-Key

string

required

Identifies one logical mutation across retries.

Required string length: 1 - 255

Pattern: ^[\x21-\x7e]{1,255}$

Path Parameters

string

required

Body

application/json

code

string

required

Required string length: 1 - 1024

phoneNumberId

string

required

Required string length: 1 - 64

wabaId

string

required

Required string length: 1 - 64

Response

The code was accepted and onboarding was dispatched. GET the Location after the Retry-After interval until the operation is terminal.

cancellable

boolean

required

createdAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Example:

"2026-01-01T00:00:00.000Z"

operationId

string

required

projectId

string

required

resourceType

string

required

state

enum<string>

required

Available options:

pending,

running,

succeeded,

failed,

cancelled

type

enum<string>

required

Available options:

resource.provision,

resource.release,

whatsapp.account.disconnect,

sms.campaign.assign,

sms.campaign.unassign

updatedAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Example:

"2026-01-01T00:00:00.000Z"

detail

object

Show child attributes

endedAt

string<date-time>

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Example:

"2026-01-01T00:00:00.000Z"

error

object

Show child attributes

reason

enum<string>

Available options:

charge_refused,

entitlement_lost,

project_deleted

resourceId

string

startedAt

string<date-time>

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Example:

"2026-01-01T00:00:00.000Z"

⌘I

Get started

Problems

Endpoints

Event Delivery WebSocket

Event schemas

Connect WhatsApp Business

Authorizations

Headers

Path Parameters

Body

Response