Skip to content

Move SMS text content from Twilio templates to codebase #489

@blink-claw-bot

Description

@blink-claw-bot

Summary

SMS text content for payment notifications is currently stored in Twilio's Content Template system (referenced via TWILIO_WELCOME_CONTENT_SID env var) rather than in the codebase. This should be moved inline to make the SMS content:

  1. AI-agentic friendly — AI assistants working on the codebase cannot read, modify, or iterate on SMS text that lives in Twilio's dashboard. Moving content to the codebase enables automated review, testing, and iteration.
  2. Version-controlled — SMS text changes should go through PR review like any other user-facing copy.
  3. Testable — Unit tests can verify SMS content, catch content-filter trigger words, and validate i18n.
  4. Visible — The team can see what SMS messages say without needing Twilio dashboard access.

Current implementation

In src/services/twilio-service.ts, the sendSms() function uses Twilio's Content API:

await twilioClient.messages.create({
  contentSid: TWILIO_WELCOME_CONTENT_SID,
  contentVariables: JSON.stringify({ ... }),
  to: phoneNumber,
  messagingServiceSid: TWILIO_MESSAGING_SERVICE_SID,
})

The actual text of the SMS is defined in the Twilio dashboard as a Content Template, not in the codebase.

Proposed change

Replace Twilio Content Template usage with inline message body:

await twilioClient.messages.create({
  body: `Your message text here with ${variables}`,
  to: phoneNumber,
  messagingServiceSid: TWILIO_MESSAGING_SERVICE_SID,
})

This allows:

  • SMS text to be defined in the codebase (potentially in a locale/messages file)
  • Easy iteration on wording to avoid operator content filtering (see query that should probably be mutations GaloyMoney/blink#3699)
  • PR-based review of any text changes
  • AI agents to read, suggest, and implement SMS text improvements

Context

  • Related to SMS delivery issues in Kenya where operator content filtering is blocking messages (query that should probably be mutations GaloyMoney/blink#3699 on blink-mobile)
  • The inability to see/modify SMS text from the codebase makes debugging and fixing content filtering issues much harder
  • Twilio Content Templates were likely chosen for compliance/approval workflows, but for transactional SMS this can be handled with a standard messaging service SID

Note on Twilio Content API compliance

Some regions require pre-approved templates (e.g., WhatsApp). For plain SMS, using body directly is supported and common. If any compliance requirements mandate Content Templates, those should be documented as exceptions.

cc @grimen @dolcalmi

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions