Phone numbers

For branding, business verification, marketing permission and review next steps, see Keep your WhatsApp account in good standing.

Two sources

Source also determines control and exit behavior. See WABA and phone-number ownership before choosing a long-lived sender: BYON stays under your control, while a Salvy number is a Tyxter-managed rental with no published port-out guarantee.

List available regions

Returns DDDs Salvy currently has stock for, with the monthly BRL rental fee for each.

Rent a Salvy number: orders and approval

In production, complete the legal business-identity declaration first. When the default-off deployment policy PHONE_PROVISIONING_REQUIRE_BILLING_WHATSAPP is enabled, complete the separate billing WhatsApp alert step in dashboard Settings → Business identity too: a current owner or admin must have a dashboard-verified WhatsApp identity and explicitly consent to transactional billing alerts. This is not the legal KYC contact phone. Under that policy, order creation and provision return 403 billing_whatsapp_required before an order is written, and the approval checks it again; existing rentals, sandbox, and BYON connect are unaffected.

In production, Tyxter rents a number only after an owner or admin of the organization approves it. Each production number is a phone line held in your organization's name, and a person on your team must be responsible for it. So an owner or admin authorizes every rental themselves; an agent or API key cannot. A standard API key with phone_numbers:write can ask for a number; agent keys cannot hold that scope.

curl https://api.tyxter.com/v1/phone-numbers/orders \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: order-sales-line-1" \
  -d '{ "ddd": "11", "display_name": "ACME Suporte", "purpose": "Support line" }'

A production order answers 201 with status: "awaiting_approval", a priced preview of the activation fee and each later charge, terms_version, expires_at (24 hours after the preview) and approval_url. Nothing is rented, reserved or charged yet. Hand approval_url to an owner or admin: it opens the order's approval page in the dashboard, which shows the order's charge summary, the rental terms and a link to the renewal policy. Any organization member with access to the order's project can view the order there (owners and admins always can), and only an owner or admin can approve or decline it. No API route approves an order, and no webhook or notification announces one, so relaying the link is how the approver learns about it.

In the dashboard, an owner or admin who rents a number approves it in the wizard's confirm step. A member who starts one gets the approval link to pass to an owner or admin.

Read the order about once a minute until it reaches a final status. Reading spends no provision rate-limit token, but it is refused with 402 credit_balance_exhausted while production credit is exhausted.

A declined or expired order rented and charged nothing: create a new order. Approving re-runs the business-identity, billing WhatsApp, plan allowance and Tyxter-provisioned number limit checks and needs the whole activation fee in the balance; a refused approval, such as 402 insufficient_balance, leaves the order awaiting approval until it expires. When the price or a charge date cannot be determined, creation answers 503 phone_number_rental_preview_unavailable and creates nothing; retry later.

Order creation and provision share one per-organization rate limit (burst 5, sustained 10/hour). A replay of the same Idempotency-Key returns the order as it was created, not its current status, and still spends a token first, so with an empty bucket it answers 429 rate_limited. Without a key every request creates a new order that needs its own approval. The provisioning feature control blocks order creation, never the order read or the dashboard decision.

Provision (Salvy)

curl https://api.tyxter.com/v1/phone-numbers/provision \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "ddd": "11", "display_name": "ACME Suporte" }'

In sandbox, provision returns 202 with a simulated number, and a sandbox order is approved on creation with a free preview: sandbox needs no approver, business identity or balance. In production, provision creates a rental order and returns 409 phone_number_rental_approval_required; error.details.order carries the order's id, approval_url and expires_at (TyxterApiError.rentalOrder in the JavaScript SDK). Hand the link to an owner or admin and read the order; do not also create one with POST /v1/phone-numbers/orders. A keyed replay answers the 409 stored at creation, so read the order for its status.

Once approved, the actual Salvy call runs on the provider.phone worker pool. Watch the status transitions:

requested  →  provisioning  →  provisioned  →  verifying  →  active

Salvy forwards the SMS verification code via webhook and we stash it on the row. Fetch with GET /v1/phone-numbers/:id to read verification_code and verification_code_received_at.

Register a Salvy number with Meta

Carrier activation and Meta registration are separate. A production Salvy number can be active while meta_phone_number_id is null; it is still pending Meta registration. Continue in the dashboard's WhatsApp connection flow.

1. In Meta, choose SMS, not a voice call, for the verification method.
2. The verification SMS reaches the Tyxter-provisioned number through Salvy. After Salvy receives it, the code appears in the Tyxter dashboard.
3. Copy the code from the dashboard and enter it in Meta's registration wizard.

This is the Meta registration step for a Salvy number; POST /v1/phone-numbers/connect is for a number you already registered with Meta.

To move an already-registered number to a different WABA or Business Portfolio, run WhatsApp Embedded Signup again from dashboard Connections → Meta and select the target Business Portfolio, WABA, and number. No disconnect or release is required for this dashboard rerun; your Salvy rental stays in place. Read the move guide for relinking, template resync, and effects on other numbers.

Connect (BYON)

curl https://api.tyxter.com/v1/phone-numbers/connect \
  -H "authorization: Bearer $TYXTER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "phone": "+5511999999999",
    "meta_phone_number_id": "109...",
    "display_name": "ACME Vendas"
  }'

BYON numbers skip Salvy and jump straight to verifying. You complete WhatsApp verification on your side; Tyxter transitions the row to active when that finishes.

Import a selected Salvy account number

After connecting a customer Salvy account, choose one cached account-owned number and send its connection and resource ids with continuation_terms_version: "salvy_byok_v1" and an Idempotency-Key. Tyxter creates a customer-owned BYON phone and keeps the returned nullable salvy_management enrollment record. Listing inventory never imports it. The import call itself does not provision, release, or rent a Tyxter phone, call Salvy, or write wallet, fee, rental-cycle, or usage records.

Importing needs an active Standard or Growth plan; without one the call returns 403 salvy_byok_subscription_required. While the plan stays active, and through the end of the UTC month in which it ends, Tyxter charges nothing to manage an imported number. After that, keeping that management costs a monthly management fee (the phone.management.month meter): one full fee for each UTC calendar month, charged from your balance on the 1st, as the renewal policy describes. On the free plan, a number whose month is still unpaid at 12:00 UTC on the last UTC day of that month is disabled. While neither a plan nor a charged month covers the number, for example after it is disabled, sending from it fails with phone_service_suspended. The number is not released. Each number’s salvy_management on GET /v1/phone-numbers reports billing’s live coverage, next charge and state, with suspension_reason while suspended; GET /v1/billing/phone-management adds payment status and the disable deadline. End management for free with convert-to-byon below.

Complete imported Salvy registration

Send the imported phone's Meta phone id and an Idempotency-Key. The response is 202 while Tyxter independently confirms that id belongs to the same environment's Meta WABA. A connected Salvy account or received SMS alone never activates WhatsApp messaging.

End optional customer Salvy management

A customer-owned BYON phone can send exactly {} with anIdempotency-Key to keep the same phone and Meta link while its nullablesalvy_management becomes null. This free exit does not release or deregister the customer resource and stays available after a customer connection is disconnected. It is an idempotent no-op for ordinary BYON; platform Salvy rentals and foreign ids return the usual non-enumerating 404.

Meta display names

Every phone-number response, including list, retrieve, and mutation responses, includesverified_name, pending_name_review, and name_review.display_name remains the customer-entered label for the row; it is not Meta's verified display name.

In production, verified_name is populated only by Tyxter's scheduled Meta health sweep and is null before a completed sweep observes it. Sandbox returns a deterministic simulated verified name from its health snapshot. Reading either response never makes a provider call.

pending_name_review is the current pending Graph health observation, not a completed decision. It is either null or { requested_name: string | null; status: string | null; observed_at: ISO timestamp }. Its raw status is open Meta vocabulary, and observed_at is the same successful-sweep freshness fact as meta_health_synced_at. A successful complete production health sweep is authoritative and writes or clears the block. A completed callback can clear it immediately only when its requested name matches and its effective time is not older than observed_at; all other callbacks wait for the next sweep. A failed or partial refresh leaves its prior values and freshness untouched. Sandbox deterministically returns pending_name_review: null without calling Meta, and that null means no pending Graph observation — not that a review was approved.

name_review is null until Tyxter has durably received a completed callback decision. Once present it contains requested_name, decision, reason, and reviewed_at; requested_name and reason may be null. Treat decision as an open Meta string rather than a fixed enum. It is separate from both pending_name_review and the name_status in the existing health webhook snapshot.

A name-review update appears in the dashboard and can create an email notification when your notification preferences allow it. It does not add a signed customer webhook; API clients should read the phone resource for the current result.

Release a number

Returns 202. Salvy numbers move to release_requested while a worker cancels the line at Salvy; the row reaches released as soon as Salvy accepts the cancellation or reports the line already gone. If Salvy fails otherwise, the number stays release_requested while Tyxter retries. BYON numbers move directly to released. A Tyxter-rented number keeps billing until you release it: the release request (status release_requested) stops further monthly charges. Disconnecting it with DELETE /v1/phone-numbers/{id} does not stop billing.

Billing

A number Tyxter provisions for you pays a monthly rental (the phone.number.month meter). Ordering a number in sandbox is free and reserves nothing. A number you bring yourself costs nothing to keep. An imported Salvy number is the exception from the 1st after the UTC month in which your Standard or Growth plan ends: it then pays the monthly management fee described under Renewal policy. These rules summarize How number rental is billed, which also gives dated examples.

• One full fee per UTC calendar month, never prorated. The activation fee pays for the whole month in which the number becomes active, whatever the day. A number activated on the 30th pays for that month and, if you keep it, for the whole next month too.
• The activation fee is reserved when an owner or admin approves the order, not when the order is created. Approval needs the whole fee in your balance, otherwise it fails with 402 insufficient_balance and the order keeps waiting for approval until it expires. If provisioning fails before delivery, the reservation is returned to your balance.
• Each later month is charged on its 1st, from 00:05 UTC, for the month that starts, with a ledger line dated the 1st of that month. Nothing is reserved ahead of the month, and the charge is debited in full even when that takes your balance below -R$5.
• At or below -R$5, production API keys and MCP are blocked until you top up. On the free plan, a number whose month is still unpaid on the last UTC day of that month is released; the month’s charge is not refunded. On a paid plan, an unpaid number is not released automatically.
• A project spend limit never refuses a rental fee, but counts it toward the month its ledger line is dated in.
• The fee returns to the balance automatically only when provisioning fails; once the line is provisioned it is non-refundable, in full or in part. Releasing a number never refunds a month that has already been charged (see Billing → Refunds). A disconnected number that Tyxter still holds at the carrier keeps billing until you release it.

Renewal policy

A number Tyxter rents for you renews every UTC calendar month, and the monthly rental is charged on the 1st of each month, for the month that starts. The renewal notices arrive by email and in the dashboard; each states what applies to that number at the moment it is sent, with every figure read from your account at that moment. This policy applies from the November 2026 renewal.

• The first month is paid in full, never prorated: its fee is reserved when an owner or admin approves the rental order and charged when the carrier delivers the number.
• Seven days before a month starts you receive a renewal notice: the fee, your balance when the notice was sent, the rental charges due on the 1st and, when the balance is short, the top-up needed. When auto top-up is on with a saved card and its amount covers the shortfall, the notice says so instead of asking you to top up.
• A number that becomes active during those seven days gets its notice from the next daily run, at 00:12 UTC, before the 1st. One that becomes active on the month’s last UTC day after 00:12 UTC is charged on the 1st without that notice.
• From 00:05 UTC on the 1st, the month’s rental is charged for every number you hold. The charge goes through even if your balance cannot cover it, and your balance then shows the debt. Nothing is reserved before the month starts.
• If a charge leaves your balance negative, you are told by email and in the dashboard; on the free plan that notice names the day the number will be released. At or below -R$5, production API keys and MCP are blocked until you top up; sandbox keeps working.
• Top up any time before the last UTC day of the month to keep the number: once your balance is back at zero or above, that month counts as paid. Lifting the -R$5 block alone is not enough.
• On the free plan, while the month stays unpaid, you are reminded by email and in the dashboard seven days and again 24 hours before the release.
• On the free plan, a number still unpaid on the last UTC day of the month is released to the carrier. A month is unpaid while your balance stays below zero after its charge. The charge is not refunded, and a released number cannot be recovered.
• On a paid plan, an unpaid number is not released automatically. The charge stays on your balance, and production sending stays blocked at or below -R$5 until you top up.
• Top up in Billing in the dashboard. Releasing a number stops future renewals; a month that has already been charged is not refunded.

Imported Salvy numbers

A number imported from your own Salvy account pays no rental. Once your Standard or Growth plan ends, its monthly management fee (the phone.management.month meter) follows the same calendar:

• The plan covers the whole UTC month in which it ends, at no fee. The first fee is charged on the 1st of the next month.
• Each month is charged one full fee on its 1st, for the month that starts, never prorated. A number in service at the end of the previous month is charged even if your balance cannot cover the fee, and your balance then shows the debt. The seven-day renewal notice lists rental charges only.
• With auto top-up on, a management charge that brings your balance down to its threshold or below starts the top-up, as a rental charge does.
• If a charge leaves your balance negative, the notice names how many imported numbers the month’s charges include and their fees. On the free plan it also names when they will be disabled, and the reminders seven days and 24 hours before name them too.
• On the free plan, a number whose month is still unpaid at 12:00 UTC on the last UTC day of the month is disabled, and you are told by email and in the dashboard. From then on, sending from it fails with phone_service_suspended. The number stays imported, Tyxter does not touch the line at Salvy, and the month’s fee is not refunded.
• Top up before then to keep the number in service: once your balance is back at zero or above, that month counts as paid. On a paid plan, an unpaid imported number is not disabled; the fee stays on your balance.
• A disabled number is charged again only once your balance covers one full fee. It comes back in one of three ways: top up until your balance covers one full fee, and it is charged one full fee and serves again from the next month’s 1st (if you top up after that 1st, as soon as the next charge runs, normally within a minute); subscribe to Standard or Growth, which covers it at once; or end management for free with convert-to-byon, which keeps it as a number you bring yourself. A top-up does not charge or restore the month in which it was disabled.

Webhooks

• phone_number.verified — first active transition.
• phone_number.disconnected — Salvy or Meta disconnected the number.
• phone_number.released — number release completed.
• phone_number.tier_changed — Meta reported a new phone throughput tier (the send-rate cap).
• phone_number.quality_changed — Meta’s quality rating for the number moved (for example green to red).
• phone_number.messaging_tier_changed — Meta’s daily unique-recipient health observation moved. For linked Meta phones it describes the shared Business Portfolio allowance, rather than a second per-phone quota. A different axis from phone_number.tier_changed above: this one concerns how many new people the portfolio may reach per day, that one is how fast one phone may send.
• phone_number.name_status_changed — Meta’s display-name review state moved (for example APPROVED to DECLINED).
• phone_number.messaging_limit_paused / phone_number.messaging_limit_resumed — Tyxter stopped, then restarted, starting NEW conversations on the number because its active allowance ran out. For linked Meta phones that allowance is shared by the Business Portfolio; an open customer-service window remains specific to the sending phone. Not a failure: affected messages stay queued and send by themselves once allowance frees up, and replies inside an open conversation window keep flowing throughout. These report Tyxter’s own pacing, not a move by Meta — that is phone_number.messaging_tier_changed above.

The pause/resume pair fires on the transition, not per message, so a ten-thousand-message broadcast produces exactly one paused. The resume is OBSERVED rather than scheduled: Tyxter reports it when a send to a new recipient next succeeds, so a paused number that stops sending stays paused and emits nothing. Never wait for a resume before sending again — sending is what produces it. Read the remaining allowance itself from remaining_messaging_allowance_estimate on the number. A linked Meta phone reports its quality-adjusted estimate against shared portfolio usage there. An unlinked Meta phone uses the conservative per-phone fallback; sandbox follows its deterministic simulated phone tier. Read the per-message reason from status_reason on held messages.

The three health events each carry the full health snapshot — quality_rating, meta_quality_rating, messaging_tier, messaging_limit_tier, name_status, and meta_health_synced_at — plus the previous value of whichever dimension moved, so you never need a follow-up retrieve. They fire only on a real change: the first time a number’s health is read is not a change, and re-reading the same value emits nothing. Production only — a sandbox number never reaches Meta and takes a constant simulated health snapshot instead.

What to do when Tyxter paces a number

This is not a total-message limit. Meta limits the unique WhatsApp recipients a business can deliver messages to outside an open customer-service window during a moving 24-hour period. Here, “new recipient” means a recipient who does not already hold a slot in that rolling period — not a phone number you have never contacted before.

• The first out-of-window send to a recipient reserves one slot. Outside the service window, WhatsApp allows that send only as an approved template.
• More messages to the same recipient while that slot remains active do not reserve more slots.
• A message from the customer opens a separate 24-hour customer-service window for that customer and that sending phone. Replies — and templates sent during that open window — do not use the unique-recipient allowance.
• After both relevant windows have expired, contacting the same recipient outside a service window can reserve a slot again.

When the allowance is full, Tyxter holds only sends that need another slot. Messages to a recipient with an active slot, and messages inside that recipient's customer-service window, keep flowing. Slots expire one by one, so there is no daily reset time. A number stays paused until the messages deferred behind the pause have all been sent, so a busy sender does not flap between paused and resumed as individual slots free up. The dashboard can show an earliest time that a slot may free up, but it is an estimate, not a promise that sending resumes at that time.

The effective pacing cap applies the configured safety margin, then a quality ratio for the sending phone. Default ratios are GREEN 100%, YELLOW 50%, and RED 25%; unknown quality uses the configured GREEN ratio. With margin 100%, a raw allowance of 250 yields caps of 250, 125, and 62. This cap is a threshold, not a count of messages sent, and it does not replace the raw Meta health tier.

Linked Meta senders share Business Portfolio recipient usage. Each sending phone compares that shared usage with its own quality-adjusted cap. A GREEN sibling may have room when a YELLOW phone is paced, but moving traffic does not create a new portfolio allowance. Health recovery is picked up by automatic retries; it does not promise an immediate resume, and the deferred-backlog guard still applies.

For a finite pacing cap, pause notifications and emails describe a recorded Yellow or Red multiplier below 100%, before rounding. Alerts without a finite cap or quality context keep neutral wording. Dashboard phone detail shows current quality pacing context for finite caps, which can differ from the earlier alert. A Green rating does not mean queued messages have completed.

Watch the paused state on the dashboard phone roster and detail view, the paced label in message list and detail views, and the notification bell. A held message has status_reason: "messaging_limit_pacing"; see the message status_reason reference. It stays queued, retries automatically, and must not be resent or re-created — doing so can duplicate a customer message.

Subscribe webhook receivers to phone_number.messaging_limit_paused and phone_number.messaging_limit_resumed to observe the live transition. Existing endpoints keep their saved subscriptions, so endpoints created before these events may need both names added to subscribed_events. New endpoints created in the dashboard suggest the full event catalog, including both pacing events, by default.

For remediation, review the number's quality, verification, and current messaging-limit information in WhatsApp Manager and Meta's guidance. Follow Meta's Messaging Limits guidance and Account Quality; do not rely on a published promotion threshold because Meta can change its current criteria.

{
  "id": "pn_abc",
  "object": "phone_number",
  "source": "salvy",
  "status": "active",
  "environment": "production",
  "display_name": "Tyxter Brazil",
  "ddd": "11",
  "phone": "+5511987654321",
  "provider_number_id": "salvy_456",
  "meta_phone_number_id": "456_phone",
  "waba_id": null,
  "quality_rating": "unknown",
  "messaging_tier": "unknown",
  "messaging_limit_tier": null,
  "meta_throughput_tier": null,
  "meta_quality_rating": null,
  "verified_name": null,
  "pending_name_review": null,
  "name_review": null,
  "meta_health_synced_at": null,
  "current_24h_unique_recipients": 0,
  "remaining_messaging_allowance_estimate": 225,
  "verification_code": null,
  "verification_code_received_at": null,
  "monthly_fee_brl": "49.90",
  "error_code": null,
  "error_message": null,
  "created_at": "2026-04-25T10:00:00Z",
  "updated_at": "2026-04-25T11:30:00Z",
  "activated_at": "2026-04-25T11:30:00Z",
  "released_at": null,
  "recent_messages": [],
  "renewal": {
    "state": "at_risk",
    "reason_codes": [
      "insufficient_credit"
    ],
    "cycle_id": null,
    "amount_brl": "49.9000",
    "currency": "brl",
    "next_renewal_at": "2026-12-01T00:05:00.000Z",
    "release_cutoff_at": "2026-11-30T12:00:00.000Z",
    "renewal_warning_48h_at": null,
    "renewal_warning_24h_at": null,
    "grace_selected_at": null,
    "grace_ends_at": null,
    "automatic_release_enabled": true,
    "release_requested_at": null,
    "recommended_action": "add_credit_or_enable_auto_topup",
    "evaluated_at": "2026-11-10T12:00:00.000Z",
    "provider_evidence_observed_at": null
  }
}

{
  "state": "at_risk",
  "reason_codes": [
    "insufficient_credit"
  ],
  "cycle_id": null,
  "amount_brl": "49.9000",
  "currency": "brl",
  "next_renewal_at": "2026-12-01T00:05:00.000Z",
  "release_cutoff_at": null,
  "renewal_warning_48h_at": null,
  "renewal_warning_24h_at": null,
  "grace_selected_at": null,
  "grace_ends_at": null,
  "automatic_release_enabled": false,
  "release_requested_at": null,
  "recommended_action": "add_credit_or_enable_auto_topup",
  "evaluated_at": "2026-11-10T12:00:00.000Z",
  "provider_evidence_observed_at": null
}

{
  "state": "upcoming",
  "reason_codes": [],
  "cycle_id": null,
  "amount_brl": "49.9000",
  "currency": "brl",
  "next_renewal_at": "2026-12-01T00:05:00.000Z",
  "release_cutoff_at": null,
  "renewal_warning_48h_at": null,
  "renewal_warning_24h_at": null,
  "grace_selected_at": null,
  "grace_ends_at": null,
  "automatic_release_enabled": true,
  "release_requested_at": null,
  "recommended_action": "none",
  "evaluated_at": "2026-11-10T12:00:00.000Z",
  "provider_evidence_observed_at": null
}