Skip to content
/
ContextSMS Webex Bot API...
Last updated

ContextSMS Webex Bot API Integration Guide

Overview

The ContextSMS Webex Bot API lets you connect phone numbers with Webex messaging. When people send SMS/MMS to a phone number, messages appear in Webex. When a Webex team replies, the reply is forwarded as an SMS/MMS to the customer.

Who Uses This API

  • Customers: Companies that want Webex teams to receive and send text messages.
  • CSPs (Communication Service Providers): Messaging providers who manage phone numbers and integrations for their business customers.

Key Features

  • Enterprise Management: Create and manage customer organizations (enterprises).
  • Phone Number Mapping: Map phone numbers to Webex bot identities.
  • Authentication: JWT Bearer tokens and refresh flow.
  • Webhooks: Real-time inbound message event delivery.
  • Environments: Distinct development and production environments.

Quick Integration Flow

  1. Authenticate → call /auth/login to obtain accessToken + refreshToken.
  2. Create Enterprise → POST /enterprise/{cspId} to register the customer organization.
  3. Add Mapping → POST /mapping/add/{enterpriseId} to link a phone number to a Webex bot.
  4. Receive Events → implement a webhook endpoint to receive inbound message events.
  5. Send Messages → call API endpoints or let the system forward messages from Webex to SMS.

Base URLs

Use these hosts consistently in examples and your client implementations. Replace {api_base} with the chosen environment.

  • Production API Base: https://context-webex.sabrhub.com/api/v1
  • Development API Base: https://webex-dev-frontend.sabrhub.com/api/v1
  • Authentication (Auth Service): https://usermanagement.sabrhub.com/v1

Tip: Use server variables in generated SDKs or documentation tooling so you only change one place when switching environments.

Authentication

All protected endpoints require a valid Bearer token in the Authorization header.

Authorization: Bearer <accessToken>

Auth Flow (Primary)

  1. Login — exchange username/password for accessToken (JWT) and refreshToken.
  2. Refresh — call the refresh endpoint to exchange refreshToken for a new accessToken.

POST /auth/login

URL (Auth service): https://usermanagement.sabrhub.com/v1/auth/login

Request

{
  "username": "your-email@company.com",
  "password": "your-password"
}

Success Response (200)

{
  "username": "your-email@company.com",
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "expirationTimeInUTC": "2025-10-14T12:34:56Z",
  "roles": ["CSP_ADMIN"],
  "tenantId": "tenant123",
  "services": ["context-webex"]
}

cURL example

curl -X POST "https://usermanagement.sabrhub.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-email@company.com",
    "password": "your-password"
  }'

POST /auth/getaccesstoken

URL (Auth service): https://usermanagement.sabrhub.com/v1/auth/getaccesstoken

Request

{
  "username": "your-email@company.com",
  "refreshToken": "<REFRESH_TOKEN>"
}

Success Response (200) same schema as /auth/login.

Common Headers

  • Authorization: Bearer <accessToken> (required for protected endpoints)
  • Content-Type: application/json
  • Accept: application/json

Schemas

Use these field names consistently across endpoints and examples.

  • Enterprise

    • enterpriseId (string)
    • name (string)
    • contact (string)
    • phoneNumber (string, E.164)
    • email (string)
    • defaultMmsSelection (boolean)
    • webexSettings (object | null)
    • numberToMessageAppMaps (array | null)
    • createdDate (integer, epoch ms)
    • updateDate (integer, epoch ms)

  • Number Mapping

    • numberToMessageAppMapId (string)
    • messagingAppId (string) — e.g., the Webex bot ID
    • phoneNumber (string) — E.164
    • messagingAppType (string) — e.g., Webex
    • mmsEnabled (boolean)

  • AuthResponse

    • accessToken (string)
    • refreshToken (string)
    • expirationTimeInUTC (date-time)

  • ErrorResponse

    • error (string)
    • code (string | integer) optional error code
    • details (object | null) optional additional info

API Endpoints

All endpoints shown against the canonical API base: https://context-webex.sabrhub.com/api/v1 (swap with dev base as needed).

Authentication

POST /auth/login

(Defined earlier auth service host https://usermanagement.sabrhub.com/v1)

POST /auth/getaccesstoken

(Defined earlier auth service host https://usermanagement.sabrhub.com/v1)

Enterprise Management

POST /enterprise/{cspId} Create Enterprise

URL: POST https://context-webex.sabrhub.com/api/v1/enterprise/{cspId}

Path parameter

  • cspId CSP identifier (e.g., CSP001)

Request body

{
  "name": "ABC Marketing Company",
  "contact": "Sarah Johnson",
  "phoneNumber": "+15551234567",
  "email": "sarah@abcmarketing.com",
  "defaultMmsSelection": true
}

Success Response (201 Created)

{
  "enterpriseId": "E0000123",
  "name": "ABC Marketing Company",
  "contact": "Sarah Johnson",
  "phoneNumber": "+15551234567",
  "email": "sarah@abcmarketing.com",
  "deleted": false,
  "createdDate": 1698446777442,
  "updateDate": 1698446777443,
  "webexSettings": null,
  "numberToMessageAppMaps": null,
  "defaultMmsSelection": true
}

cURL

curl -X POST "https://context-webex.sabrhub.com/api/v1/enterprise/CSP001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ABC Marketing Company",
    "contact": "Sarah Johnson",
    "phoneNumber": "+15551234567",
    "email": "sarah@abcmarketing.com",
    "defaultMmsSelection": true
  }'

GET /enterprise/getenterprise/{enterpriseId} Get Enterprise

URL: GET https://context-webex.sabrhub.com/api/v1/enterprise/getenterprise/{enterpriseId}

Success (200) returns the Enterprise object shown above.

cURL

curl -X GET "https://context-webex.sabrhub.com/api/v1/enterprise/getenterprise/E0000123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

DELETE /enterprise/deleteenterprise/{enterpriseId} Delete Enterprise

URL: DELETE https://context-webex.sabrhub.com/api/v1/enterprise/deleteenterprise/{enterpriseId}

Success (204 No Content) no body returned. If your API returns a message object, treat 200 as accepted but prefer 204.

cURL

curl -X DELETE "https://context-webex.sabrhub.com/api/v1/enterprise/deleteenterprise/E0000123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Mapping Management

** Mapping payload fields:** messagingAppId, phoneNumber, messagingAppType, and mmsEnabled (optional).

POST /mapping/add/{enterpriseId} Create Number Mapping

URL: POST https://context-webex.sabrhub.com/api/v1/mapping/add/{enterpriseId}

Request body

{
  "messagingAppId": "webex-bot-12345",
  "phoneNumber": "+15551234567",
  "messagingAppType": "Webex",
  "mmsEnabled": true
}

Success Response (201 Created)

{
  "numberToMessageAppMapId": "NTMAP0000456",
  "messagingAppId": "webex-bot-12345",
  "phoneNumber": "+15551234567",
  "messagingAppType": "Webex",
  "mmsEnabled": true
}

cURL

curl -X POST "https://context-webex.sabrhub.com/api/v1/mapping/add/E0000123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messagingAppId": "webex-bot-12345",
    "phoneNumber": "+15551234567",
    "messagingAppType": "Webex",
    "mmsEnabled": true
  }'

GET /mappings/enterprise/{enterpriseId} List Mappings for an Enterprise

URL: GET https://context-webex.sabrhub.com/api/v1/mappings/enterprise/{enterpriseId}

Success Response (200) Array of Number Mapping objects.

cURL

curl -X GET "https://context-webex.sabrhub.com/api/v1/mappings/enterprise/E0000123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET /mappings/csp/{cspId} List Mappings for a CSP

URL: GET https://context-webex.sabrhub.com/api/v1/mappings/csp/{cspId}

Supports optional pagination and filters (page, size, status). Returns an array of Number Mapping objects.

DELETE /mapping/{mappingId} Delete Mapping

URL: DELETE https://context-webex.sabrhub.com/api/v1/mapping/{mappingId}

Success (204 No Content) mapping removed. If the API returns a JSON message, treat 200 with a message as acceptable, but 204 is preferred.

curl -X DELETE "https://context-webex.sabrhub.com/api/v1/mapping/NTMAP0000456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Webhooks (Inbound Events)

Integrators must implement an HTTPS endpoint to receive inbound message events (SMS → Webex flow). The platform will POST events to your webhook when messages arrive.

Important: Use HTTPS endpoints with valid TLS certificates. The platform may perform a verification handshake (challenge) — if you support webhook registration, implement a verification step that responds to challenge tokens.

Suggested webhook schema

POST /webhooks/messages (customer webhook endpoint — this is the endpoint you implement to receive events):

{
  "eventType": "message.received",
  "timestamp": "2025-10-14T12:00:00Z",
  "message": {
    "messageId": "MSG123456",
    "phoneNumber": "+15559871234",
    "from": "+15551230001",
    "to": "+15559871234",
    "text": "Hello, I need help",
    "media": [
      {
        "url": "https://.../mms/abcd.jpg",
        "contentType": "image/jpeg"
      }
    ]
  },
  "enterpriseId": "E0000123",
  "mappingId": "NTMAP0000456"
}

Response (200) return HTTP 200 quickly to acknowledge receipt. If your endpoint is unavailable, our platform will retry according to exponential backoff rules.

Error Codes & Handling

Standardize on a JSON ErrorResponse:

{
  "error": "Invalid phone number format",
  "code": "INVALID_PHONE",
  "details": {
    "field": "phoneNumber",
    "message": "Phone number must be E.164 format"
  }
}

Common HTTP status codes

  • 200 OK — successful GET or other operations that return a body.
  • 201 Created — resource created (POST /enterprise, POST /mapping/add).
  • 204 No Content — delete succeeded, no response body.
  • 400 Bad Request — invalid input/data.
  • 401 Unauthorized — missing or invalid token.
  • 403 Forbidden — user lacks permission.
  • 404 Not Found — resource not found (enterprise/mapping).
  • 429 Too Many Requests — rate limit exceeded.
  • 500+ — server errors.

Development vs Production Guidance

  • Development/Testing

    • Use the development API base: https://webex-dev-frontend.sabrhub.com/api/v1
    • Use test phone numbers and test Webex bot identities.
    • Configure a local/ngrok HTTPS webhook endpoint for receiving events during development.

  • Production

    • Use the production API base: https://context-webex.sabrhub.com/api/v1
    • Ensure secure storage for accessToken and refreshToken.
    • Implement retries, logging, and monitoring for webhooks and API calls.

Environment switching

Use server variables or an environment config file for API_BASE so users cannot accidentally call production while testing.

Best Practices & Recommendations

  • Use E.164 format for phone numbers (e.g., +15551234567).
  • Implement token refresh using /auth/getaccesstoken before accessToken expiry.
  • Handle retries and idempotency for POSTs where the client may accidentally retry (use client-generated idempotency keys if supported).
  • Log incoming webhook payloads (temporarily in dev only) to aid debugging.
  • Validate incoming messages for allowed content and size, and sanitize text before forwarding to Webex.

Examples Full Flow (Quick)

  1. Login (Auth):
curl -X POST "https://usermanagement.sabrhub.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin@csp.com","password":"YourPass"}'
  1. Create enterprise (API):
curl -X POST "https://context-webex.sabrhub.com/api/v1/enterprise/CSP001" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name":"BrightStar Marketing","contact":"Mike Chen","phoneNumber":"+15559871234","email":"mike@brightstar.com","defaultMmsSelection":true}'
  1. Add mapping
curl -X POST "https://context-webex.sabrhub.com/api/v1/mapping/add/E0000124" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"messagingAppId":"brightstar-webex-bot","phoneNumber":"+15559871234","messagingAppType":"Webex","mmsEnabled":true}'
  1. Test message
  • Send SMS to +15559871234 → webhook or Webex will receive and forward it to the mapped Webex bot/team.

Operational Notes

  • Monitoring: set up alerting if webhook delivery fails (exceeding retry thresholds) or if API rate limits are reached.
  • Security: rotate tokens periodically and do not store tokens in client-side code.
  • Support: when contacting support, include enterpriseId and numberToMessageAppMapId in your message to support@sabrhub.com.

Change Log

  • 2025-10-14 Canonicalized hostnames, aligned mapping request/response fields, added webhook schema, standardized status codes, improved examples.

Appendix: Quick Reference

  • Auth: POST https://usermanagement.sabrhub.com/v1/auth/login
  • Refresh: POST https://usermanagement.sabrhub.com/v1/auth/getaccesstoken
  • Create enterprise: POST https://context-webex.sabrhub.com/api/v1/enterprise/{cspId}
  • Get enterprise: GET https://context-webex.sabrhub.com/api/v1/enterprise/getenterprise/{enterpriseId}
  • Delete enterprise: DELETE https://context-webex.sabrhub.com/api/v1/enterprise/deleteenterprise/{enterpriseId}
  • Add mapping: POST https://context-webex.sabrhub.com/api/v1/mapping/add/{enterpriseId}
  • List mappings (enterprise): GET https://context-webex.sabrhub.com/api/v1/mappings/enterprise/{enterpriseId}
  • List mappings (CSP): GET https://context-webex.sabrhub.com/api/v1/mappings/csp/{cspId}
  • Delete mapping: DELETE https://context-webex.sabrhub.com/api/v1/mapping/{mappingId}
Previous page
Next page