urbanairship Register and Associate SMS Workflow
This workflow registers an SMS phone number and associates it with a named user.
Prerequisites
- Airship account with API access
- SMS phone number (MSISDN)
- Sender code
- Named user ID
Skills Required
Step 1 (Optional): Lookup SMS Channel
Registration in Step 2 handles both new and existing channels, so this lookup is optional. Use it only if you want to inspect a channel without modifying it:
GET /api/channels/sms/15035556789/12345
Authorization: Bearer <token>
Response (if exists):
{
"ok": true,
"channel": {
"channel_id": "existing-channel-id",
"msisdn": "15035556789",
"sender": "12345",
"opt_in": true
}
}
Response (if not exists):
{
"ok": false,
"error": "A channel_id does not exist for the msisdn and sender."
}
Step 2: Register SMS (if needed)
If lookup returns 404, register the SMS number:
POST /api/channels/sms
Authorization: Bearer <token>
Content-Type: application/json
{
"msisdn": "15035556789",
"sender": "12345",
"opted_in": "2024-01-15T10:30:00",
"timezone": "America/Los_Angeles",
"locale_country": "US",
"locale_language": "en"
}
Response:
{
"ok": true,
"channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
"opt_in": true
}
Step 3: Associate with Named User
Use the channel_id from Step 1 or Step 2 to associate with a named user:
POST /api/named_users/associate
Authorization: Bearer <token>
Content-Type: application/json
{
"named_user_id": "user_12345",
"channel_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
"device_type": "sms"
}
Response:
{
"ok": true
}
Outcomes
- SMS channel registered or updated
- SMS channel associated with named user
- channel_id available for future operations
Use Cases
- User onboarding from website forms
- SMS channel registration
- Bulk user import
- CRM integration