docs
/
AI skills

Register a number for texting (A2P 10DLC)

A US local number made able to send business texts — the business (brand) and the number's campaign filled from what the platform knows, checked for the usual rejection reasons, submitted on a yes, followed until the carriers approve it, then made the default texting number.

In the US, a business text from an ordinary local number must be registered with the carriers first. This is A2P 10DLC. It has two parts:

PartWhat it isHow manyStored on
Brandthe business itself: legal name, EIN, address, the person signing for itone per business, reused by every numberthe business's company record (data.meta.twilio.a2p)
Campaignwhat one number texts, to whom, and how they agreedone per numberthe number's phone record, data.smsRegistration

An unregistered number fails quietly: the carrier accepts the text and then drops it, so the sender sees success and the customer gets nothing. Registering costs money and is reviewed by people outside Appmint. This skill fills the form, makes it pass the platform's own check, and stops for a yes before anything is submitted.

For texting a group once a number can send, see SMS broadcast to a group. For buying a number and how it answers calls, see Business phone number and call routing.

Ask first

  • Which number? One of the business's local US numbers (phone, data.phoneNumberType = local).
  • What will it text, and to whom? Appointment reminders, order updates, replies to questions, offers. Marketing texts need the use case marketing or mixed.
  • How do people agree to get texts? The exact place: a checkbox on a booking form, a sign-up page, texting a keyword. The link to it. If there is no such place yet, say so: carriers reject a campaign without a real opt-in, and the platform's own forms don't add one (see The site's sign-up form).
  • The business's legal details, exactly as on its IRS papers: legal name, EIN (9 digits), business type, industry, street address, and the person authorised to register it (name, email, phone, job title). The AI may find most of these; it must not invent any.
  • Does the website have a privacy policy and SMS terms? If not, may the AI publish them on the business's site (step 3)?

Steps

1. Phone & SMS: where the number stands

Find the number: find_records on phone by data.phoneNumber (E.164, e.g. +12145550142). Take its sk and read data.phoneNumberType, data.capabilities.sms and data.smsRegistration.

smsRegistration.statusScreen badgeMeaning
unregistered with requiresRegistration: trueRegistration Requirednot submitted; texts will be dropped
waiting_for_brandBusiness in reviewthe brand is with the registry; the campaign goes in as soon as it is approved
pendingCampaign in reviewthe campaign is with the carriers
registeredA2P Verifiedit can text
rejectedNot approvedfailedStep says brand or campaign, failureReason says why

Also read the business's brand: call_appengine GET /phone/a2p/brand. null means none yet. A brand with a brandRegistrationSid and brandStatus other than FAILED is reused: a second number only needs its campaign, and no second brand fee is charged.

  • registered already: skip to step 6.
  • waiting_for_brand or pending: nothing to submit. Go to step 5.
  • rejected: read failureReason, then fix what it names in step 2 and resubmit.
  • Not local (toll-free, short code, or outside the US): this skill doesn't apply. See What it can't do yet.
  • capabilities.sms false: the number can't text at all. Turning it on is a setting in the number's Phone Configuration › Capabilities, and is the person's choice.

GET /phone/numbers/<phone sk>/sms-requirements describes what the number type needs. Its fee figures are general guidance, not what the business is charged (see the Stop).

Hands on: the phone's sk, and whether a brand exists. Check: the number's row on Configuration › Phone & SMS (/phone-system) shows the badge in the SMS Registration column.

2. Phone & SMS: the form, filled

call_appengine GET /phone/a2p/draft?phoneId=<phone sk> returns the whole form, filled from what the platform knows: the brand if there is one, the business profile and company record, the signed-in person as the representative, the site's address and its sms-terms / privacy-policy pages, and this number's previous submission (so a rejected one is a small edit). platform.ready: false means registration isn't open on this platform yet; stop and say so. It is not the business's to fix.

The body for the check and the submission:

FieldValue
useCaselow_volume (mixed, a few thousand a day), customer_care, transactional, marketing or mixed
brandTierlow_volume (what the screen always uses: a Standard brand without extra vetting, usually approved in minutes). standard (full vetting, days) and sole_proprietor (no EIN; verified by a code texted to representative.mobilePhone, which they confirm by replying YES) are accepted by the API only.
emailthe business contact email
businesslegalName, businessType (Sole Proprietorship, Partnership, Limited Liability Corporation, Corporation, Co-operative, Non-profit Corporation), industry (e.g. FOOD_AND_BEVERAGE, RETAIL, HEALTHCARE, PROFESSIONAL_SERVICES), registrationIdentifier: "EIN", registrationNumber, websiteUrl, socialMediaUrl, regionsOfOperation (["USA_AND_CANADA"]), businessIdentity: "direct_customer", companyType (private, public, non-profit, government)
addressstreet, city, region (two-letter state), postalCode, isoCountry (US)
representativefirstName, lastName, email, phone (E.164), jobPosition (Director, GM, VP, CEO, CFO, General Counsel, Other), businessTitle
campaigndescription, messageFlow, messageSamples (at least two), hasEmbeddedLinks, hasEmbeddedPhone, ageGated, directLending, privacyPolicyUrl, termsAndConditionsUrl, and the keyword lists with their replies: optInKeywords / optInMessage, optOutKeywords / optOutMessage, helpKeywords / helpMessage

A public company also needs stockExchange, stockTicker and brandContactEmail (a company address: the registry emails it a code). A non-profit or government body registers with business type Non-profit Corporation and industry NOT_FOR_PROFIT or GOVERNMENT.

Rewrite what the draft guessed:

  • description: the draft says "…texts customers who have opted in: appointment and booking reminders, order and service updates…". Replace it with what this business really sends.
  • messageFlow: where and how people agree, with the link. The draft fills it only when the site has an sms-terms page, and that wording describes an SMS consent checkbox on the website. Keep it only if the site really has one.
  • messageSamples: written as they will really be sent. Each needs the business's name; at least one needs "Reply STOP to opt out". No bit.ly or other public link shorteners. If a sample has a link, set hasEmbeddedLinks: true.
  • businessType and industry are often empty in the draft. Ask; don't guess.

Hands on: the filled body.

3. Sites: SMS terms and a privacy policy (only on a yes)

Reviewers open the website and look for a privacy policy that says mobile numbers aren't shared or sold, and for SMS terms (what is sent, how often, how to stop). If the business has neither, the platform can publish both.

Stop: this publishes two pages on the business's live site. Say so and wait for yes. Then call_appengine POST /phone/a2p/site-pages with { business, address, email, phone } (and siteName if it isn't the default site). It copies the platform's templates, filled with the business's details, as pages sms-terms and privacy-policy, and publishes them. A page the site already has under that name is left as it is (created: false).

The answer gives each page's url and a suggestedMessageFlow. Put the urls in campaign.privacyPolicyUrl and campaign.termsAndConditionsUrl. Use the suggested flow only if its checkbox exists.

Hands on: the two page urls. Check: open both urls. Read them: the business name, address and contact details are right.

4. Phone & SMS: the pre-check

call_appengine POST /phone/a2p/check with the body. It changes nothing. It answers { ok, problems: [{ field, severity, message }], brandExists }:

  • block problems are near-certain rejections. The submission refuses them. Fix each and check again.
  • warn problems don't stop it, but show every one to the person.

What it catches (messages as the person sees them, shortened):

FieldBlocks when
business.registrationNumberno EIN, or not 9 digits ("…is not an EIN — it is 9 digits, like 12-3456789.")
business.websiteUrlmissing, not https://, or the site doesn't load. Warns when it has no privacy policy or doesn't mention texts.
address.*, representativestreet, city, state or ZIP missing; no representative name
campaign.descriptionunder about 40 characters
campaign.messageFlowunder about 40 characters, or no word for consent (opt, consent, agree, checkbox, tick, subscribe, sign up, keyword, form)
campaign.messageSamplesfewer than two; none has the first word of the business name; none says STOP; any public link shortener
campaign.privacyPolicyUrl / termsAndConditionsUrlnot a full https:// address. Warns when missing.
useCasewarns when the samples read like marketing (% off, sale, discount, promo, offer, deal, coupon) and the use case isn't marketing or mixed

When no brand exists yet, a platform block means registration isn't open on this platform. Nothing the business types will fix it.

Hands on: ok: true, and the warnings.

Stop: submit the registration

Submitting costs money and goes to the carriers' reviewers. Show the person:

  • the number, and that one brand covers all their numbers;
  • the legal name, EIN, address and representative exactly as they will be sent;
  • the use case, the description, the opt-in flow and both samples;
  • the warnings left;
  • the cost. On the platform's shared phone account the wallet is charged, by default, a one-time brand fee of $44 (only when no brand exists), a one-time campaign fee of $15 per number, and $10 a month per registered number, each before the platform's markup (100% by default). The business's own rates are on Service rates. A business on its own Twilio account is billed by Twilio instead.

A rejected brand or campaign that is submitted again is charged again.

After a clear yes: call_appengine POST /phone/numbers/register-sms/<phone sk> with the body. It runs the same check first and answers 400 with problems if anything blocks. Then it registers the brand (or reuses it), and:

  • brand approved already: submits the campaign at once. status becomes pending.
  • brand still in review: saves the campaign on the number. status becomes waiting_for_brand.

The answer is the number's smsRegistration plus warnings.

The screen does the same: the number's row menu › Register for SMS opens SMS Registration (A2P 10DLC), with Check before submitting and Submit A2P Registration.

5. Phone & SMS: follow it to approved

Nobody has to come back. A scheduled job, Text messaging registration check (a2p-watch), runs every 15 minutes while anything is waiting. It asks the carriers where the brand and each campaign stand, submits a waiting campaign the moment its brand is approved, and settles each campaign:

Carrier answerNumber becomes
campaign VERIFIEDregistered
campaign FAILEDrejected, failedStep: "campaign"
brand FAILEDrejected, failedStep: "brand"

At each step the business's owners and admins get a banner notice (SMS registration for +1…: business under review, …campaign submitted, +1… can now send texts, or …not approved with the reason).

A low-volume brand is usually approved within minutes. A campaign usually takes a few days. Don't promise a date.

GET /phone/numbers/sms-status/<phone sk> asks the carriers now and saves their brand and campaign status on the number. It does not change status itself; the watch does.

Hands on: smsRegistration.status. Check: the number's Phone Configuration › SMS Registration (A2P 10DLC) shows the four steps (Business profile, Business approved, Campaign under review, Ready to text), when it was last checked, and Check now. A rejection shows Why it was not approved and Fix and resubmit.

6. Phone & SMS: the default texting number

Texts that don't name a sender (notifications, automations) go from the business's default SMS number. GET /phone/sms-number says which one is used now. inherited: true means nobody chose it; the platform picked the first number that can text.

A number can text when it is active, has capabilities.sms, and either has no smsRegistration, is registered, or has requiresRegistration: false. Any other number is skipped when the default is worked out.

To make the newly registered number the default, ask first: it changes which number customers get texts from. Then call_appengine POST /phone/sms-number with { "phoneNumber": "+1…" }. A number that can't text is refused with "…cannot be the default SMS number: number is not registered for SMS (pending)…". Don't pass force: true to get around it.

Check: the number's Phone Configuration › Capabilities › SMS says Registered — carriers will deliver texts from this number.

When it's done

Tell the person:

  • the number and where its registration stands, in the screen's words;
  • whether a new brand was registered or the existing one reused;
  • what was charged, or will be when the campaign is submitted;
  • the pages published on their site, if any;
  • that they will get a notice when it can text, and that nothing needs doing meanwhile;
  • the default SMS number.

Open the number on Phone & SMS.

What it can't do yet

  • Toll-free verification isn't built. A toll-free number is saved as not needing registration, so the platform lets it text and doesn't offer Register for SMS. Carriers block texts from unverified toll-free numbers. Say so plainly.
  • Numbers outside the US are marked not needing registration. Rules in their country still apply.
  • The screen registers every business as low volume. For high volume or a sole proprietor, the API takes brandTier, but the screen can't show or change it.
  • A number registered outside Appmint (on the business's own Twilio account) still shows unregistered here: Check now shows the carrier's answer but doesn't save the number as registered. It can't be made the default without force.
  • The campaign's keywords and replies are what the carriers are told. The platform records a STOP only through an SMS routing with opt-out on (see SMS broadcast to a group, step 3).
  • A broadcast doesn't check registration. A broadcast's chosen sender texts even when unregistered. Only the default-number choice skips unregistered numbers.
  • No record of each customer's consent. The campaign describes how people agree; nothing stores who did.

Don'ts

  • Don't submit, resubmit or publish the compliance pages without a yes. Each costs money or changes the live site.
  • Don't invent an EIN, legal name, address, representative or opt-in method. A wrong one is rejected, and the fee is gone.
  • Don't describe a consent checkbox the business doesn't have.
  • Don't register a second brand: one brand serves every number.
  • Don't set the default SMS number with force, and don't tell the person a pending number can text.