Webhook

post

Webhook to process incoming messages from Twilio.

This function receives incoming messages from Twilio, processes the message body to check for certain keywords or commands (like "unsubscribe", "subscribe", or smart keywords), and responds accordingly.

It also manages the deduction of credits for triggering a smart keyword and handles the notification of users when a smart keyword is matched.

Workflow:

  1. Extracts the 'From', 'To', and 'Body' from the incoming request data.
  2. Verifies that the required fields ('From', 'To', 'Body') are present.
  3. Checks if the 'To' number is associated with a valid messaging number.
  4. Handles "unsubscribe" and "subscribe" commands, sending appropriate responses.
  5. Searches for a matching smart keyword and processes the hit, including credit deduction and user notifications.
  6. If no matches are found, sends an auto-response message.

:param request: The HTTP request containing the incoming message from Twilio, including 'From', 'To', and 'Body'.

:return: A Response object containing either an error message or a successful reply. - 400 (Bad Request) if required fields are missing, or if the messaging number or church is not found. - 404 (Not Found) if no church is associated with the given 'To' number. - 200 (OK) with the appropriate response message if processing is successful.

Example: When a user sends a text message to a Twilio number, the webhook processes the message and replies with the corresponding response or action (e.g., a keyword match or auto-response).

Notes: - If a user sends "unsubscribe" or "stop", the system unsubscribes them and responds accordingly. - If a user sends a valid keyword, credits are deducted from the church's balance, and the system responds with the keyword's description.

Authorizations
Body
idstring · uuidRead-onlyRequired
hit_countstringRead-onlyRequired
hitsstringRead-onlyRequired
legacy_idstring | nullableOptional
nextgen_legacy_idstring | nullableOptional
created_atstring · date-time | nullableOptional
updated_atstring · date-timeRead-onlyRequired
keywordstring · max: 50Required

The word or phrase that triggers this keyword.

descriptionstringOptional

The reply text for this keyword.

credits_deducted_per_hitinteger · max: 2147483647Optional

The number of credits deducted from the church for each hit.

message_typestring · enumOptional
  • sms - SMS
  • mms - MMS
  • voice - Voice
Possible values:
statusstring · enumOptional
  • Active - Active
  • Inactive - Inactive
Possible values:
media_urlstring · uri | nullableOptional
notify_usersstring · uuid[]Optional

Users to be notified when this keyword is triggered.

Responses
200Success
application/json
post
POST /api/unified-communications/smart-keyword/webhook HTTP/1.1
Host: prosper-api-test.churchpad.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 283

{
  "legacy_id": "text",
  "nextgen_legacy_id": "text",
  "created_at": "2025-07-23T12:24:09.070Z",
  "keyword": "text",
  "description": "text",
  "credits_deducted_per_hit": 1,
  "message_type": "sms",
  "status": "Active",
  "media_url": "https://example.com",
  "notify_users": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}
200Success
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "hit_count": "text",
  "hits": "text",
  "notify_users_display": [
    {
      "id": "text",
      "email": "text",
      "phone": "text",
      "profile": "text",
      "additional_user_fields": "text"
    }
  ],
  "legacy_id": "text",
  "nextgen_legacy_id": "text",
  "created_at": "2025-07-23T12:24:09.070Z",
  "updated_at": "2025-07-23T12:24:09.070Z",
  "keyword": "text",
  "description": "text",
  "credits_deducted_per_hit": 1,
  "message_type": "sms",
  "status": "Active",
  "media_url": "https://example.com",
  "notify_users": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}
PreviousSmart keywordNextSmart keyword hit