Phone Numbers
Phone Numbers represent the phone numbers assigned to your partner account.
Use the list phone numbers endpoint to discover which phone numbers are available for sending messages.
When creating chats, listing chats, or sending a voice memo, use one of your assigned phone numbers
in the from field.
Ineligible numbers. A number can temporarily lose the ability to deliver messages.
While it is in that state, requests that would produce new activity on it — sending a
message, creating a chat, reacting, typing, group actions — are rejected with 403
(error code 2027) before anything is created. Reads keep working, so your existing
chats, messages, and history stay available. Omit from on POST /v3/messages and we
pick an eligible number for you, skipping ineligible ones; if none of your assigned
numbers are eligible, you get 409 (no from number was ever chosen, so there’s no
specific number to blame with a 403).
Update a phone number
Start a line reputation audit
Get a line reputation audit
ModelsExpand Collapse
class ReputationAudit: …
status: Literal["pending", "complete", "error"]pending until the report is ready — poll until complete or error.
pending until the report is ready — poll until complete or error.
When the report was generated; signals reflect the line at this moment.
report: Optional[ReputationReport]Present only when status is complete.
Present only when status is complete.
Ranked, highest impact first.
Ranked, highest impact first.
key: Optional[ReputationDriverKey]Stable driver-category identifier — what is dragging the line, or one
of its conversations, down.
low_engagement — The conversation is one-sided: several messages
sent, few or no replies back. Pause or rework outreach where
recipients are not replying, and lead with messages that invite a
response. Conversation-level: it appears on
evidence.unhealthy_chats[].driver_keys, never in drivers.overall_conversation_health — A large share of the line’s active
conversations are trending unhealthy. Fix the unhealthy conversations
first — review their content and timing, and whether recipients are
engaging.volume_spike — The line’s daily sending volume jumped far above its
own normal level while few recipients were replying, or exceeded the
recommended daily volume for a single line. Ramp volume gradually
instead of spiking, prioritize people who have already engaged with
you, and spread sustained high volume across additional lines.new_conversation_rate — The line is starting too many brand-new
conversations in a single day. Spread new conversations out over time
instead of starting many at once.opt_out_handling — Recipients asked this line to stop. Honor every
stop request immediately: send nothing further to that recipient
unless they opt back in. Every send to them is rejected with 403
(error code 2024), including a final courtesy message — to send
one telling them they can reply to resume, set
override_optout: true on that single request.flagged — The line is currently restricted and its messages may not
be reaching recipients. Move active traffic to a healthy line now,
and let this one recover before sending more.other — Fallback for a signal without dedicated partner copy.
Stable driver-category identifier — what is dragging the line, or one of its conversations, down.
low_engagement— The conversation is one-sided: several messages sent, few or no replies back. Pause or rework outreach where recipients are not replying, and lead with messages that invite a response. Conversation-level: it appears onevidence.unhealthy_chats[].driver_keys, never indrivers.overall_conversation_health— A large share of the line’s active conversations are trending unhealthy. Fix the unhealthy conversations first — review their content and timing, and whether recipients are engaging.volume_spike— The line’s daily sending volume jumped far above its own normal level while few recipients were replying, or exceeded the recommended daily volume for a single line. Ramp volume gradually instead of spiking, prioritize people who have already engaged with you, and spread sustained high volume across additional lines.new_conversation_rate— The line is starting too many brand-new conversations in a single day. Spread new conversations out over time instead of starting many at once.opt_out_handling— Recipients asked this line to stop. Honor every stop request immediately: send nothing further to that recipient unless they opt back in. Every send to them is rejected with403(error code2024), including a final courtesy message — to send one telling them they can reply to resume, setoverride_optout: trueon that single request.flagged— The line is currently restricted and its messages may not be reaching recipients. Move active traffic to a healthy line now, and let this one recover before sending more.other— Fallback for a signal without dedicated partner copy.
evidence: Optional[ReputationEvidence]The specific conversations behind the drivers, so partners can verify every claim against their own send logs. Each chat_id can be fetched via GET /v3/chats/{chatId} — its current health appears there.
The specific conversations behind the drivers, so partners can verify every claim against their own send logs. Each chat_id can be fetched via GET /v3/chats/{chatId} — its current health appears there.
The key of the most important driver. Empty string when the line has nothing to act on — the report then carries a single reassurance action item. Its values are the ReputationDriverKey vocabulary — see that schema for what each means and what to do about it.
severity: Optional[Literal["HEALTHY", "AT_RISK", "CRITICAL"]]Current reputation of this phone line.
HEALTHY — The line is in good standing. Send normally.AT_RISK — Warning signs on the line: engagement is low across many of its conversations, or it’s starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line’s send pace, avoid opening many new conversations at once, and review your messaging patterns.CRITICAL — Strong signals that messages from this line aren’t landing well. Pause outbound on the line until it recovers.
Defaults to HEALTHY for lines that have not yet been scored.
Current reputation of this phone line.
HEALTHY— The line is in good standing. Send normally.AT_RISK— Warning signs on the line: engagement is low across many of its conversations, or it’s starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line’s send pace, avoid opening many new conversations at once, and review your messaging patterns.CRITICAL— Strong signals that messages from this line aren’t landing well. Pause outbound on the line until it recovers.
Defaults to HEALTHY for lines that have not yet been scored.
class ReputationDriver: …
key: Optional[ReputationDriverKey]Stable driver-category identifier — what is dragging the line, or one
of its conversations, down.
low_engagement — The conversation is one-sided: several messages
sent, few or no replies back. Pause or rework outreach where
recipients are not replying, and lead with messages that invite a
response. Conversation-level: it appears on
evidence.unhealthy_chats[].driver_keys, never in drivers.overall_conversation_health — A large share of the line’s active
conversations are trending unhealthy. Fix the unhealthy conversations
first — review their content and timing, and whether recipients are
engaging.volume_spike — The line’s daily sending volume jumped far above its
own normal level while few recipients were replying, or exceeded the
recommended daily volume for a single line. Ramp volume gradually
instead of spiking, prioritize people who have already engaged with
you, and spread sustained high volume across additional lines.new_conversation_rate — The line is starting too many brand-new
conversations in a single day. Spread new conversations out over time
instead of starting many at once.opt_out_handling — Recipients asked this line to stop. Honor every
stop request immediately: send nothing further to that recipient
unless they opt back in. Every send to them is rejected with 403
(error code 2024), including a final courtesy message — to send
one telling them they can reply to resume, set
override_optout: true on that single request.flagged — The line is currently restricted and its messages may not
be reaching recipients. Move active traffic to a healthy line now,
and let this one recover before sending more.other — Fallback for a signal without dedicated partner copy.
Stable driver-category identifier — what is dragging the line, or one of its conversations, down.
low_engagement— The conversation is one-sided: several messages sent, few or no replies back. Pause or rework outreach where recipients are not replying, and lead with messages that invite a response. Conversation-level: it appears onevidence.unhealthy_chats[].driver_keys, never indrivers.overall_conversation_health— A large share of the line’s active conversations are trending unhealthy. Fix the unhealthy conversations first — review their content and timing, and whether recipients are engaging.volume_spike— The line’s daily sending volume jumped far above its own normal level while few recipients were replying, or exceeded the recommended daily volume for a single line. Ramp volume gradually instead of spiking, prioritize people who have already engaged with you, and spread sustained high volume across additional lines.new_conversation_rate— The line is starting too many brand-new conversations in a single day. Spread new conversations out over time instead of starting many at once.opt_out_handling— Recipients asked this line to stop. Honor every stop request immediately: send nothing further to that recipient unless they opt back in. Every send to them is rejected with403(error code2024), including a final courtesy message — to send one telling them they can reply to resume, setoverride_optout: trueon that single request.flagged— The line is currently restricted and its messages may not be reaching recipients. Move active traffic to a healthy line now, and let this one recover before sending more.other— Fallback for a signal without dedicated partner copy.
Literal["low_engagement", "overall_conversation_health", "volume_spike", 4 more]Stable driver-category identifier — what is dragging the line, or one
of its conversations, down.
low_engagement — The conversation is one-sided: several messages
sent, few or no replies back. Pause or rework outreach where
recipients are not replying, and lead with messages that invite a
response. Conversation-level: it appears on
evidence.unhealthy_chats[].driver_keys, never in drivers.overall_conversation_health — A large share of the line’s active
conversations are trending unhealthy. Fix the unhealthy conversations
first — review their content and timing, and whether recipients are
engaging.volume_spike — The line’s daily sending volume jumped far above its
own normal level while few recipients were replying, or exceeded the
recommended daily volume for a single line. Ramp volume gradually
instead of spiking, prioritize people who have already engaged with
you, and spread sustained high volume across additional lines.new_conversation_rate — The line is starting too many brand-new
conversations in a single day. Spread new conversations out over time
instead of starting many at once.opt_out_handling — Recipients asked this line to stop. Honor every
stop request immediately: send nothing further to that recipient
unless they opt back in. Every send to them is rejected with 403
(error code 2024), including a final courtesy message — to send
one telling them they can reply to resume, set
override_optout: true on that single request.flagged — The line is currently restricted and its messages may not
be reaching recipients. Move active traffic to a healthy line now,
and let this one recover before sending more.other — Fallback for a signal without dedicated partner copy.
Stable driver-category identifier — what is dragging the line, or one of its conversations, down.
low_engagement— The conversation is one-sided: several messages sent, few or no replies back. Pause or rework outreach where recipients are not replying, and lead with messages that invite a response. Conversation-level: it appears onevidence.unhealthy_chats[].driver_keys, never indrivers.overall_conversation_health— A large share of the line’s active conversations are trending unhealthy. Fix the unhealthy conversations first — review their content and timing, and whether recipients are engaging.volume_spike— The line’s daily sending volume jumped far above its own normal level while few recipients were replying, or exceeded the recommended daily volume for a single line. Ramp volume gradually instead of spiking, prioritize people who have already engaged with you, and spread sustained high volume across additional lines.new_conversation_rate— The line is starting too many brand-new conversations in a single day. Spread new conversations out over time instead of starting many at once.opt_out_handling— Recipients asked this line to stop. Honor every stop request immediately: send nothing further to that recipient unless they opt back in. Every send to them is rejected with403(error code2024), including a final courtesy message — to send one telling them they can reply to resume, setoverride_optout: trueon that single request.flagged— The line is currently restricted and its messages may not be reaching recipients. Move active traffic to a healthy line now, and let this one recover before sending more.other— Fallback for a signal without dedicated partner copy.
class ReputationEvidence: …The specific conversations behind the drivers, so partners can verify every claim against their own send logs. Each chat_id can be fetched via GET /v3/chats/{chatId} — its current health appears there.
The specific conversations behind the drivers, so partners can verify every claim against their own send logs. Each chat_id can be fetched via GET /v3/chats/{chatId} — its current health appears there.
class ReputationReport: …
Ranked, highest impact first.
Ranked, highest impact first.
key: Optional[ReputationDriverKey]Stable driver-category identifier — what is dragging the line, or one
of its conversations, down.
low_engagement — The conversation is one-sided: several messages
sent, few or no replies back. Pause or rework outreach where
recipients are not replying, and lead with messages that invite a
response. Conversation-level: it appears on
evidence.unhealthy_chats[].driver_keys, never in drivers.overall_conversation_health — A large share of the line’s active
conversations are trending unhealthy. Fix the unhealthy conversations
first — review their content and timing, and whether recipients are
engaging.volume_spike — The line’s daily sending volume jumped far above its
own normal level while few recipients were replying, or exceeded the
recommended daily volume for a single line. Ramp volume gradually
instead of spiking, prioritize people who have already engaged with
you, and spread sustained high volume across additional lines.new_conversation_rate — The line is starting too many brand-new
conversations in a single day. Spread new conversations out over time
instead of starting many at once.opt_out_handling — Recipients asked this line to stop. Honor every
stop request immediately: send nothing further to that recipient
unless they opt back in. Every send to them is rejected with 403
(error code 2024), including a final courtesy message — to send
one telling them they can reply to resume, set
override_optout: true on that single request.flagged — The line is currently restricted and its messages may not
be reaching recipients. Move active traffic to a healthy line now,
and let this one recover before sending more.other — Fallback for a signal without dedicated partner copy.
Stable driver-category identifier — what is dragging the line, or one of its conversations, down.
low_engagement— The conversation is one-sided: several messages sent, few or no replies back. Pause or rework outreach where recipients are not replying, and lead with messages that invite a response. Conversation-level: it appears onevidence.unhealthy_chats[].driver_keys, never indrivers.overall_conversation_health— A large share of the line’s active conversations are trending unhealthy. Fix the unhealthy conversations first — review their content and timing, and whether recipients are engaging.volume_spike— The line’s daily sending volume jumped far above its own normal level while few recipients were replying, or exceeded the recommended daily volume for a single line. Ramp volume gradually instead of spiking, prioritize people who have already engaged with you, and spread sustained high volume across additional lines.new_conversation_rate— The line is starting too many brand-new conversations in a single day. Spread new conversations out over time instead of starting many at once.opt_out_handling— Recipients asked this line to stop. Honor every stop request immediately: send nothing further to that recipient unless they opt back in. Every send to them is rejected with403(error code2024), including a final courtesy message — to send one telling them they can reply to resume, setoverride_optout: trueon that single request.flagged— The line is currently restricted and its messages may not be reaching recipients. Move active traffic to a healthy line now, and let this one recover before sending more.other— Fallback for a signal without dedicated partner copy.
evidence: Optional[ReputationEvidence]The specific conversations behind the drivers, so partners can verify every claim against their own send logs. Each chat_id can be fetched via GET /v3/chats/{chatId} — its current health appears there.
The specific conversations behind the drivers, so partners can verify every claim against their own send logs. Each chat_id can be fetched via GET /v3/chats/{chatId} — its current health appears there.
The key of the most important driver. Empty string when the line has nothing to act on — the report then carries a single reassurance action item. Its values are the ReputationDriverKey vocabulary — see that schema for what each means and what to do about it.
severity: Optional[Literal["HEALTHY", "AT_RISK", "CRITICAL"]]Current reputation of this phone line.
HEALTHY — The line is in good standing. Send normally.AT_RISK — Warning signs on the line: engagement is low across many of its conversations, or it’s starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line’s send pace, avoid opening many new conversations at once, and review your messaging patterns.CRITICAL — Strong signals that messages from this line aren’t landing well. Pause outbound on the line until it recovers.
Defaults to HEALTHY for lines that have not yet been scored.
Current reputation of this phone line.
HEALTHY— The line is in good standing. Send normally.AT_RISK— Warning signs on the line: engagement is low across many of its conversations, or it’s starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line’s send pace, avoid opening many new conversations at once, and review your messaging patterns.CRITICAL— Strong signals that messages from this line aren’t landing well. Pause outbound on the line until it recovers.
Defaults to HEALTHY for lines that have not yet been scored.
class PhoneNumberListResponse: …
phone_numbers: List[PhoneNumber]List of phone numbers assigned to the partner
List of phone numbers assigned to the partner
reputation: PhoneNumberReputation[BETA] Current reputation for a phone line. Always present — lines start at HEALTHY and may shift based on aggregate engagement and delivery signals across all conversations on the line.
Unlike chat health, line reputation does not include opted_out — opt-out applies to individual recipients, not the whole line.
See the Phone Reputation guide for what each status means and how to react.
[BETA] Current reputation for a phone line. Always present — lines start at HEALTHY and may shift based on aggregate engagement and delivery signals across all conversations on the line.
Unlike chat health, line reputation does not include opted_out — opt-out applies to individual recipients, not the whole line.
See the Phone Reputation guide for what each status means and how to react.
Deep-link to the relevant section of the Phone Reputation guide for this status.
status: Literal["HEALTHY", "AT_RISK", "CRITICAL"]Current reputation of this phone line.
HEALTHY — The line is in good standing. Send normally.AT_RISK — Warning signs on the line: engagement is low across many of its conversations, or it’s starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line’s send pace, avoid opening many new conversations at once, and review your messaging patterns.CRITICAL — Strong signals that messages from this line aren’t landing well. Pause outbound on the line until it recovers.
Defaults to HEALTHY for lines that have not yet been scored.
Current reputation of this phone line.
HEALTHY— The line is in good standing. Send normally.AT_RISK— Warning signs on the line: engagement is low across many of its conversations, or it’s starting too many brand-new conversations in a single day — and a spike in send volume can add to either. Slow the line’s send pace, avoid opening many new conversations at once, and review your messaging patterns.CRITICAL— Strong signals that messages from this line aren’t landing well. Pause outbound on the line until it recovers.
Defaults to HEALTHY for lines that have not yet been scored.