Keywords

Shortcode opt-in and opt-out subscriptions triggered by inbound SMS.

A keyword is an inbound SMS trigger registered against a shortcode sender ID. When a subscriber texts the keyword to the shortcode (for example JOIN to opt in or STOP to opt out), an auto-response is delivered and the event can start a survey or workflow. Keywords require admin approval before they go live.

List keywords

GET/api/v1/keywords

Query params

sender_id

string

Filter by sender ID UUID

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/keywords?sender_id=sid-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Request a keyword

POST/api/v1/keywords

Parameters

sender_idreq

string

Shortcode sender ID UUID

keywordreq

string

The keyword text (e.g. JOIN, STOP)

keyword_aliases

string[]

Additional aliases for the keyword

auto_response

string

SMS auto-reply sent when the keyword is received

description

string

Internal description of the keyword purpose

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/keywords" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sender_id": "sid-uuid",
  "keyword": "JOIN",
  "keyword_aliases": [
    "JIUNGE",
    "START"
  ],
  "auto_response": "You have subscribed to Acme updates. Reply STOP to unsubscribe.",
  "description": "Opt-in keyword for promotional messages"
}'

Update a keyword

PATCH/api/v1/keywords/{uuid}

Parameters

keyword_aliases

string[]

Updated aliases list

auto_response

string

Updated auto-reply message

description

string

Updated description

curl -X PATCH "https://timisha-solutions-api.salamu.co.ke/api/v1/keywords/keyword-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "auto_response": "Thanks for joining. Reply STOP to unsubscribe.",
  "description": "Updated opt-in copy"
}'

Delete a keyword

DELETE/api/v1/keywords/{uuid}

curl -X DELETE "https://timisha-solutions-api.salamu.co.ke/api/v1/keywords/keyword-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

200: OK

{
  "success": true,
  "data": {
    "uuid": "keyword-uuid",
    "keyword": "JOIN",
    "approval_status": "pending"
  }
}

Handling opt-outs

Pair a STOP keyword with your Blacklist so unsubscribed numbers are skipped on every future send.