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).

List phone numbers

client.PhoneNumbers.List(ctx) (*PhoneNumberListResponse, error)

GET/v3/phone_numbers

Update a phone number

client.PhoneNumbers.Update(ctx, phoneNumberID, body) (*PhoneNumberUpdateResponse, error)

PUT/v3/phone_numbers/{phoneNumberId}

Start a line reputation audit

client.PhoneNumbers.StartReputationAudit(ctx, phoneNumber) (*ReputationAuditStarted, error)

POST/v3/phone_numbers/{phoneNumber}/reputation_audit

Get a line reputation audit

client.PhoneNumbers.GetReputationAudit(ctx, auditID, query) (*ReputationAudit, error)

GET/v3/phone_numbers/{phoneNumber}/reputation_audit/{auditId}

ModelsExpand Collapse

type ReputationActionItem struct{…}

Detail stringOptional

ExpectedImpact ReputationActionItemExpectedImpactOptional

One of the following:

const ReputationActionItemExpectedImpactHigh ReputationActionItemExpectedImpact = "high"

const ReputationActionItemExpectedImpactMedium ReputationActionItemExpectedImpact = "medium"

const ReputationActionItemExpectedImpactLow ReputationActionItemExpectedImpact = "low"

Priority int64Optional

1 = do first

Title stringOptional

type ReputationAudit struct{…}

AuditID string

Status ReputationAuditStatus

pending until the report is ready — poll until complete or error.

One of the following:

const ReputationAuditStatusPending ReputationAuditStatus = "pending"

const ReputationAuditStatusComplete ReputationAuditStatus = "complete"

const ReputationAuditStatusError ReputationAuditStatus = "error"

Error stringOptional

Present only when status is error. Short, generic reason safe to display.

GeneratedAt TimeOptional

When the report was generated; signals reflect the line at this moment.

formatdate-time

Phone stringOptional

The line audited, E.164.

Report ReputationReportOptional

Present only when status is complete.

ActionItems []ReputationActionItemOptional

Ordered by priority; 1 = do first.

Detail stringOptional

ExpectedImpact ReputationActionItemExpectedImpactOptional

One of the following:

const ReputationActionItemExpectedImpactHigh ReputationActionItemExpectedImpact = "high"

const ReputationActionItemExpectedImpactMedium ReputationActionItemExpectedImpact = "medium"

const ReputationActionItemExpectedImpactLow ReputationActionItemExpectedImpact = "low"

Priority int64Optional

1 = do first

Title stringOptional

Drivers []ReputationDriverOptional

Ranked, highest impact first.

Key ReputationDriverKeyOptional

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.

One of the following:

const ReputationDriverKeyLowEngagement ReputationDriverKey = "low_engagement"

const ReputationDriverKeyOverallConversationHealth ReputationDriverKey = "overall_conversation_health"

const ReputationDriverKeyVolumeSpike ReputationDriverKey = "volume_spike"

const ReputationDriverKeyNewConversationRate ReputationDriverKey = "new_conversation_rate"

const ReputationDriverKeyOptOutHandling ReputationDriverKey = "opt_out_handling"

const ReputationDriverKeyFlagged ReputationDriverKey = "flagged"

const ReputationDriverKeyOther ReputationDriverKey = "other"

Metric stringOptional

A specific observed figure when available; otherwise a short qualitative note.

Summary stringOptional

One plain-English sentence.

Evidence ReputationEvidenceOptional

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.

OptOutChats []ReputationOptOutChatOptional

Worst first — most messages sent after the stop request; honor these immediately.

ChatID stringOptional

MessagesAfterStop int64Optional

Outbound messages sent after the recipient asked to stop.

UnhealthyChats []ReputationUnhealthyChatOptional

Up to 15, worst first.

ChatID stringOptional

DriverKeys []ReputationDriverKeyOptional

What is dragging this conversation down, in the same vocabulary as the report’s drivers. Each key’s meaning and the fix for it are documented on ReputationDriverKey.

One of the following:

const ReputationDriverKeyLowEngagement ReputationDriverKey = "low_engagement"

const ReputationDriverKeyOverallConversationHealth ReputationDriverKey = "overall_conversation_health"

const ReputationDriverKeyVolumeSpike ReputationDriverKey = "volume_spike"

const ReputationDriverKeyNewConversationRate ReputationDriverKey = "new_conversation_rate"

const ReputationDriverKeyOptOutHandling ReputationDriverKey = "opt_out_handling"

const ReputationDriverKeyFlagged ReputationDriverKey = "flagged"

const ReputationDriverKeyOther ReputationDriverKey = "other"

Status ReputationUnhealthyChatStatusOptional

The conversation’s current health — the same value GET /v3/chats/{chatId} reports for it.

One of the following:

const ReputationUnhealthyChatStatusAtRisk ReputationUnhealthyChatStatus = "AT_RISK"

const ReputationUnhealthyChatStatusCritical ReputationUnhealthyChatStatus = "CRITICAL"

const ReputationUnhealthyChatStatusOptedOut ReputationUnhealthyChatStatus = "OPTED_OUT"

PrimaryDriver stringOptional

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 ReputationReportSeverityOptional

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.

One of the following:

const ReputationReportSeverityHealthy ReputationReportSeverity = "HEALTHY"

const ReputationReportSeverityAtRisk ReputationReportSeverity = "AT_RISK"

const ReputationReportSeverityCritical ReputationReportSeverity = "CRITICAL"

SummaryMarkdown stringOptional

Deterministic markdown rendering of this report, suitable for feeding directly to automated systems and AI agents as investigation context. Rendered from the structured fields above, which remain the source of truth.

type ReputationAuditStarted struct{…}

AuditID string

Identifier for this audit. Poll GET /v3/phone_numbers/{phoneNumber}/reputation_audit/{auditId} until status is complete or error.

Status ReputationAuditStartedStatus

A newly started audit is pending.

One of the following:

const ReputationAuditStartedStatusPending ReputationAuditStartedStatus = "pending"

const ReputationAuditStartedStatusComplete ReputationAuditStartedStatus = "complete"

const ReputationAuditStartedStatusError ReputationAuditStartedStatus = "error"

type ReputationDriver struct{…}

Key ReputationDriverKeyOptional

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.

One of the following:

const ReputationDriverKeyLowEngagement ReputationDriverKey = "low_engagement"

const ReputationDriverKeyOverallConversationHealth ReputationDriverKey = "overall_conversation_health"

const ReputationDriverKeyVolumeSpike ReputationDriverKey = "volume_spike"

const ReputationDriverKeyNewConversationRate ReputationDriverKey = "new_conversation_rate"

const ReputationDriverKeyOptOutHandling ReputationDriverKey = "opt_out_handling"

const ReputationDriverKeyFlagged ReputationDriverKey = "flagged"

const ReputationDriverKeyOther ReputationDriverKey = "other"

Metric stringOptional

A specific observed figure when available; otherwise a short qualitative note.

Summary stringOptional

One plain-English sentence.

type ReputationDriverKey string

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.

One of the following:

const ReputationDriverKeyLowEngagement ReputationDriverKey = "low_engagement"

const ReputationDriverKeyOverallConversationHealth ReputationDriverKey = "overall_conversation_health"

const ReputationDriverKeyVolumeSpike ReputationDriverKey = "volume_spike"

const ReputationDriverKeyNewConversationRate ReputationDriverKey = "new_conversation_rate"

const ReputationDriverKeyOptOutHandling ReputationDriverKey = "opt_out_handling"

const ReputationDriverKeyFlagged ReputationDriverKey = "flagged"

const ReputationDriverKeyOther ReputationDriverKey = "other"

type ReputationEvidence struct{…}

OptOutChats []ReputationOptOutChatOptional

Worst first — most messages sent after the stop request; honor these immediately.

ChatID stringOptional

MessagesAfterStop int64Optional

Outbound messages sent after the recipient asked to stop.

UnhealthyChats []ReputationUnhealthyChatOptional

Up to 15, worst first.

ChatID stringOptional

DriverKeys []ReputationDriverKeyOptional

What is dragging this conversation down, in the same vocabulary as the report’s drivers. Each key’s meaning and the fix for it are documented on ReputationDriverKey.

One of the following:

const ReputationDriverKeyLowEngagement ReputationDriverKey = "low_engagement"

const ReputationDriverKeyOverallConversationHealth ReputationDriverKey = "overall_conversation_health"

const ReputationDriverKeyVolumeSpike ReputationDriverKey = "volume_spike"

const ReputationDriverKeyNewConversationRate ReputationDriverKey = "new_conversation_rate"

const ReputationDriverKeyOptOutHandling ReputationDriverKey = "opt_out_handling"

const ReputationDriverKeyFlagged ReputationDriverKey = "flagged"

const ReputationDriverKeyOther ReputationDriverKey = "other"

Status ReputationUnhealthyChatStatusOptional

The conversation’s current health — the same value GET /v3/chats/{chatId} reports for it.

One of the following:

const ReputationUnhealthyChatStatusAtRisk ReputationUnhealthyChatStatus = "AT_RISK"

const ReputationUnhealthyChatStatusCritical ReputationUnhealthyChatStatus = "CRITICAL"

const ReputationUnhealthyChatStatusOptedOut ReputationUnhealthyChatStatus = "OPTED_OUT"

type ReputationOptOutChat struct{…}

ChatID stringOptional

MessagesAfterStop int64Optional

Outbound messages sent after the recipient asked to stop.

type ReputationReport struct{…}

ActionItems []ReputationActionItemOptional

Ordered by priority; 1 = do first.

Detail stringOptional

ExpectedImpact ReputationActionItemExpectedImpactOptional

One of the following:

const ReputationActionItemExpectedImpactHigh ReputationActionItemExpectedImpact = "high"

const ReputationActionItemExpectedImpactMedium ReputationActionItemExpectedImpact = "medium"

const ReputationActionItemExpectedImpactLow ReputationActionItemExpectedImpact = "low"

Priority int64Optional

1 = do first

Title stringOptional

Drivers []ReputationDriverOptional

Ranked, highest impact first.

Key ReputationDriverKeyOptional

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.

One of the following:

const ReputationDriverKeyLowEngagement ReputationDriverKey = "low_engagement"

const ReputationDriverKeyOverallConversationHealth ReputationDriverKey = "overall_conversation_health"

const ReputationDriverKeyVolumeSpike ReputationDriverKey = "volume_spike"

const ReputationDriverKeyNewConversationRate ReputationDriverKey = "new_conversation_rate"

const ReputationDriverKeyOptOutHandling ReputationDriverKey = "opt_out_handling"

const ReputationDriverKeyFlagged ReputationDriverKey = "flagged"

const ReputationDriverKeyOther ReputationDriverKey = "other"

Metric stringOptional

A specific observed figure when available; otherwise a short qualitative note.

Summary stringOptional

One plain-English sentence.

Evidence ReputationEvidenceOptional

OptOutChats []ReputationOptOutChatOptional

Worst first — most messages sent after the stop request; honor these immediately.

ChatID stringOptional

MessagesAfterStop int64Optional

Outbound messages sent after the recipient asked to stop.

UnhealthyChats []ReputationUnhealthyChatOptional

Up to 15, worst first.

ChatID stringOptional

DriverKeys []ReputationDriverKeyOptional

What is dragging this conversation down, in the same vocabulary as the report’s drivers. Each key’s meaning and the fix for it are documented on ReputationDriverKey.

One of the following:

const ReputationDriverKeyLowEngagement ReputationDriverKey = "low_engagement"

const ReputationDriverKeyOverallConversationHealth ReputationDriverKey = "overall_conversation_health"

const ReputationDriverKeyVolumeSpike ReputationDriverKey = "volume_spike"

const ReputationDriverKeyNewConversationRate ReputationDriverKey = "new_conversation_rate"

const ReputationDriverKeyOptOutHandling ReputationDriverKey = "opt_out_handling"

const ReputationDriverKeyFlagged ReputationDriverKey = "flagged"

const ReputationDriverKeyOther ReputationDriverKey = "other"

Status ReputationUnhealthyChatStatusOptional

The conversation’s current health — the same value GET /v3/chats/{chatId} reports for it.

One of the following:

const ReputationUnhealthyChatStatusAtRisk ReputationUnhealthyChatStatus = "AT_RISK"

const ReputationUnhealthyChatStatusCritical ReputationUnhealthyChatStatus = "CRITICAL"

const ReputationUnhealthyChatStatusOptedOut ReputationUnhealthyChatStatus = "OPTED_OUT"

PrimaryDriver stringOptional

Severity ReputationReportSeverityOptional

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.

One of the following:

const ReputationReportSeverityHealthy ReputationReportSeverity = "HEALTHY"

const ReputationReportSeverityAtRisk ReputationReportSeverity = "AT_RISK"

const ReputationReportSeverityCritical ReputationReportSeverity = "CRITICAL"

SummaryMarkdown stringOptional

type ReputationUnhealthyChat struct{…}

ChatID stringOptional

DriverKeys []ReputationDriverKeyOptional

What is dragging this conversation down, in the same vocabulary as the report’s drivers. Each key’s meaning and the fix for it are documented on ReputationDriverKey.

One of the following:

const ReputationDriverKeyLowEngagement ReputationDriverKey = "low_engagement"

const ReputationDriverKeyOverallConversationHealth ReputationDriverKey = "overall_conversation_health"

const ReputationDriverKeyVolumeSpike ReputationDriverKey = "volume_spike"

const ReputationDriverKeyNewConversationRate ReputationDriverKey = "new_conversation_rate"

const ReputationDriverKeyOptOutHandling ReputationDriverKey = "opt_out_handling"

const ReputationDriverKeyFlagged ReputationDriverKey = "flagged"

const ReputationDriverKeyOther ReputationDriverKey = "other"

Status ReputationUnhealthyChatStatusOptional

The conversation’s current health — the same value GET /v3/chats/{chatId} reports for it.

One of the following:

const ReputationUnhealthyChatStatusAtRisk ReputationUnhealthyChatStatus = "AT_RISK"

const ReputationUnhealthyChatStatusCritical ReputationUnhealthyChatStatus = "CRITICAL"

const ReputationUnhealthyChatStatusOptedOut ReputationUnhealthyChatStatus = "OPTED_OUT"