SMS smart encoding

Typographic substitutions can push an SMS out of GSM-7. A word processor turns ' into ’, pasted text contains an em dash, or a form field carries a non-breaking space. Each looks similar to a GSM-7 character but one non-GSM character converts the whole body to UCS-2, reducing the capacity of each segment.

Smart encoding replaces those characters with their GSM-7 equivalents before Bird hands the message to the carrier, so a body that only looked non-GSM stays GSM-7 and bills as fewer segments.

Turning it on

It is off by default, because it changes the text your recipient reads. Set options.smart_encoding to true on a send:

await bird.sms.send({
  to: "+31612345678",
  from: "Bird",
  text: "Your order shipped, track it here…",
  category: "transactional",
  options: { smart_encoding: true },
});

client.sms.send(
    to="+31612345678",
    from_="Bird",
    text="Your order shipped, track it here…",
    category="transactional",
    smart_encoding=True,
)

_, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
	To:            "+31612345678",
	From:          "Bird",
	Text:          "Your order shipped, track it here…",
	Category:      bird.SMSCategoryTransactional,
	SmartEncoding: bird.Bool(true),
})

$bird->sms->send(
    to: '+31612345678',
    from: 'Bird',
    text: 'Your order shipped, track it here…',
    category: 'transactional',
    smartEncoding: true,
);

bird sms send \
  --category transactional \
  --from Bird \
  --smart-encoding=true \
  --text 'Your order shipped, track it here…' \
  --to +31612345678

curl -X POST https://eu1.platform.bird.com/v1/sms/messages \
  -H "Authorization: Bearer bk_eu1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "from": "Bird",
    "text": "Your order shipped, track it here…",
    "category": "transactional",
    "options": { "smart_encoding": true }
  }'

The Go and PHP SDKs take it as a nullable field, so leaving it unset takes Bird's default rather than sending false.

Set smart encoding per message. Bird does not provide an account-wide or per-sender setting.

When Bird keeps UCS-2

Replacement applies only when it converts the whole body to GSM-7. If any character remains outside GSM-7, Bird sends the body exactly as supplied.

A single emoji, CJK character, or accented letter outside GSM-7 keeps the whole message in UCS-2:

{ "text": "Hoe gaat het vandaag? á “" }

The “ is replaceable, but á is not in GSM-7 and has no entry in the table, so this body sends unchanged as UCS-2. GSM-7 includes à, ä, å, é, è, ì, ò, ù, ö, ñ, ü but not á, í, or ú.

Accented letters are deliberately absent from the table. Folding á to a would change the word rather than approximate it, which is the wrong trade for a sender writing Spanish or Portuguese.

Normalization affects combining accents. In NFD text, a decomposed ê stores the accent as a separate combining mark, so smart encoding converts it to e^. A precomposed ê remains unchanged and uses UCS-2.

What it does not do

• It never truncates. A body over the 12-segment cap is rejected with a 422, and the cap is measured after replacement, so opting in can bring an oversized body under it.
• It does not touch a body that is already GSM-7, which has no segments to save.
• It does not change what you are billed for beyond the segment count: the count is computed from the body as sent.

Reading back what happened

The message reports both halves. text is the body as sent, and options.smart_encoding reports the setting that applied:

{
  "text": "Your order shipped - track it here...",
  "segments": { "count": 1, "encoding": "GSM_7BIT", "characters": 36 },
  "options": { "smart_encoding": true }
}

An encoding of UCS2 on a send you opted in tells you the body could not be brought into GSM-7. To see what would happen to a specific message before you send it, paste the text into the SMS segment calculator.

The full replacement table

The replacement table lists every character changed when smart encoding is on. Other characters, including those already in GSM-7, remain unchanged.

Whitespace variants collapse to a single space (U+0020). The final row lists zero-width and formatting characters that are deleted rather than replaced.

Next steps

• Character limits: review GSM-7, UCS-2, and segment limits.
• Sending SMS: enable smart encoding on a send.
• SMS segment calculator: check a message before sending it.