ECM Communications API

Clinic endpoints for sending SMS messages and initiating phone calls to ECM patients. Communications are automatically tracked as ECM activities and events for PRTF reporting.

Overview

The ECM Communications API provides endpoints for care coordinators to communicate with patients via SMS and phone calls. All communications are integrated with Twilio for delivery and are automatically tracked as ECM activities for compliance reporting.

Communication Flow

When a communication is initiated:

Request Received: API receives the communication request
Twilio Integration: Message/call is sent via Twilio
Activity Created: An ECM activity is automatically created
Event Generated: An ECM event is generated for PRTF reporting
Response Returned: Success/failure response is returned

Send SMS

Send an SMS message to an ECM patient. The message is delivered via Twilio and automatically tracked as an ECM activity.

Endpoint: POST /v1/clinic/ecm/communications/patients/{patient_id}/sms
Authentication: Required

Path Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID

Request Body Parameters

Parameter	Type	Required	Description
`sms`	object	Yes	SMS data object
`sms.phone_number`	string	Yes	Recipient phone number (E.164 format recommended)
`sms.body`	string	Yes	Message content

Example Request


POST /v1/clinic/ecm/communications/patients/123/sms HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "sms": {
    "phone_number": "+18051234567",
    "body": "Hello! This is a reminder about your upcoming appointment. Please reply to confirm."
  }
}

Success Response


{
  "message": "SMS sent successfully",
  "sms": {
    "id": 456,
    "twilio_sid": "SM1234567890abcdef",
    "to": "+18051234567",
    "from": "+18059876543",
    "body": "Hello! This is a reminder about your upcoming appointment. Please reply to confirm.",
    "status": "queued",
    "direction": "outbound",
    "created_at": "2024-11-27T10:00:00.000Z"
  },
  "activity": {
    "id": 789,
    "activity_type": "sms",
    "status": "created",
    "patient_id": 123,
    "performed_by_id": 101,
    "assigned_to_id": 101
  }
}

Error Response - Invalid Phone Number


{
  "errors": ["Phone number is required"]
}

Error Response - Twilio Error


{
  "errors": ["Failed to send SMS: The 'To' number is not a valid phone number"]
}

Initiate Call

Initiate an outbound phone call to an ECM patient. The call is placed via Twilio and automatically tracked as an ECM activity.

Endpoint: POST /v1/clinic/ecm/communications/patients/{patient_id}/call
Authentication: Required

Path Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID

Request Body Parameters

Parameter	Type	Required	Description
`call`	object	Yes	Call data object
`call.phone_number`	string	Yes	Phone number to call (E.164 format recommended)

Example Request


POST /v1/clinic/ecm/communications/patients/123/call HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "call": {
    "phone_number": "+18051234567"
  }
}

Success Response


{
  "message": "Call initiated successfully",
  "call": {
    "id": 457,
    "twilio_sid": "CA1234567890abcdef",
    "to": "+18051234567",
    "from": "+18059876543",
    "status": "queued",
    "direction": "outbound",
    "created_at": "2024-11-27T10:00:00.000Z"
  },
  "activity": {
    "id": 790,
    "activity_type": "call",
    "status": "created",
    "patient_id": 123,
    "performed_by_id": 101,
    "assigned_to_id": 101
  }
}

Error Response - Invalid Phone Number


{
  "errors": ["Phone number is required"]
}

Error Response - Twilio Error


{
  "errors": ["Failed to initiate call: The 'To' number is not a valid phone number"]
}

Phone Number Format

Phone numbers should be provided in E.164 format for best results:

Format	Example	Recommended
E.164	`+18051234567`	Yes
National	`8051234567`	Supported
With dashes	`805-123-4567`	Supported
With parentheses	`(805) 123-4567`	Supported

Note: The system will attempt to normalize phone numbers, but E.164 format is recommended for reliability.

Inbound Communications

Inbound SMS messages and calls are automatically tracked via Twilio webhooks. When a patient responds to an SMS or calls back:

Webhook Received: Twilio sends a webhook to the API
Patient Matched: The system matches the phone number to a patient
Activity Created: An inbound activity is automatically created
Event Generated: An event is generated for PRTF reporting

Inbound SMS Webhook

Endpoint: POST /v1/clinic/webhooks/twilio/sms
Authentication: Twilio signature validation

This endpoint is called by Twilio when an inbound SMS is received. The webhook creates an inbound SMS activity for the matched patient.

Inbound Call Webhook

Endpoint: POST /v1/clinic/webhooks/twilio/voice
Authentication: Twilio signature validation

This endpoint is called by Twilio when an inbound call is received. The webhook creates an inbound call activity for the matched patient.

SMS Status Tracking

SMS messages go through several status stages:

Status	Description
`queued`	Message is queued for delivery
`sending`	Message is being sent
`sent`	Message has been sent to carrier
`delivered`	Message has been delivered to recipient
`undelivered`	Message could not be delivered
`failed`	Message failed to send

SMS Status Webhook

Endpoint: POST /v1/clinic/webhooks/twilio/sms_status
Authentication: Twilio signature validation

This endpoint receives status updates from Twilio as SMS messages progress through delivery stages.

Call Status Tracking

Phone calls go through several status stages:

Status	Description
`queued`	Call is queued
`ringing`	Call is ringing
`in-progress`	Call is in progress
`completed`	Call completed successfully
`busy`	Recipient was busy
`no-answer`	No answer
`failed`	Call failed
`canceled`	Call was canceled

Call Status Webhook

Endpoint: POST /v1/clinic/webhooks/twilio/voice_status
Authentication: Twilio signature validation

This endpoint receives status updates from Twilio as calls progress through their lifecycle.

Activity and Event Creation

When a communication is sent or received, the system automatically creates:

Activity Record

Field	Value
`activity_type`	`sms` or `call`
`status`	`created`
`patient_id`	Patient ID
`performed_by_id`	Current user ID (outbound) or system (inbound)
`assigned_to_id`	Current user ID
`text_message_id`	Twilio SMS record ID (for SMS)
`voice_call_id`	Twilio call record ID (for calls)

Event Record

Field	Value
`event_type`	`sms` or `call`
`occurred_at`	Timestamp of communication
`patient_id`	Patient ID
`activity_id`	Associated activity ID

JavaScript Example


// Send SMS
const sendSms = async (patientId, phoneNumber, body) => {
  const response = await fetch(`/v1/clinic/ecm/communications/patients/${patientId}/sms`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-User-Token': 'YOUR_TOKEN'
    },
    body: JSON.stringify({
      sms: {
        phone_number: phoneNumber,
        body: body
      }
    })
  });
  
  return response.json();
};
 
// Initiate call
const initiateCall = async (patientId, phoneNumber) => {
  const response = await fetch(`/v1/clinic/ecm/communications/patients/${patientId}/call`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-User-Token': 'YOUR_TOKEN'
    },
    body: JSON.stringify({
      call: {
        phone_number: phoneNumber
      }
    })
  });
  
  return response.json();
};
 
// Usage
await sendSms(123, '+18051234567', 'Hello! This is a reminder about your appointment.');
await initiateCall(123, '+18051234567');

TypeScript/React Example


import { useMutation } from '@tanstack/react-query';
 
interface SmsRequest {
  patientId: number;
  phoneNumber: string;
  body: string;
}
 
interface CallRequest {
  patientId: number;
  phoneNumber: string;
}
 
// Send SMS mutation
const useSendSms = () => {
  return useMutation({
    mutationFn: async ({ patientId, phoneNumber, body }: SmsRequest) => {
      const response = await fetch(
        `/v1/clinic/ecm/communications/patients/${patientId}/sms`,
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'X-User-Token': token
          },
          body: JSON.stringify({
            sms: { phone_number: phoneNumber, body }
          })
        }
      );
      return response.json();
    }
  });
};
 
// Initiate call mutation
const useInitiateCall = () => {
  return useMutation({
    mutationFn: async ({ patientId, phoneNumber }: CallRequest) => {
      const response = await fetch(
        `/v1/clinic/ecm/communications/patients/${patientId}/call`,
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'X-User-Token': token
          },
          body: JSON.stringify({
            call: { phone_number: phoneNumber }
          })
        }
      );
      return response.json();
    }
  });
};

cURL Examples

Send SMS


curl -X POST "https://your-api-domain.com/v1/clinic/ecm/communications/patients/123/sms" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: YOUR_TOKEN" \
  -d '{
    "sms": {
      "phone_number": "+18051234567",
      "body": "Hello! This is a reminder about your appointment."
    }
  }'

Initiate Call


curl -X POST "https://your-api-domain.com/v1/clinic/ecm/communications/patients/123/call" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: YOUR_TOKEN" \
  -d '{
    "call": {
      "phone_number": "+18051234567"
    }
  }'

Error Handling

Common Errors

Error	Cause	Solution
`Phone number is required`	Missing phone number	Provide a valid phone number
`Patient not found`	Invalid patient ID	Verify patient ID exists
`Invalid phone number`	Malformed phone number	Use E.164 format
`Twilio error`	Twilio service issue	Check Twilio status, retry

Twilio Error Codes

Common Twilio error codes you may encounter:

Code	Description
21211	Invalid ‘To’ phone number
21214	’To’ phone number cannot be reached
21610	Message blocked (opt-out)
21408	Permission to send SMS not enabled

Best Practices

Phone Number Format: Use E.164 format (+1XXXXXXXXXX) for reliability
Message Length: Keep SMS messages under 160 characters when possible
Opt-Out Compliance: Respect patient opt-out requests
Error Handling: Implement retry logic for transient failures
Activity Tracking: Verify activities are created for all communications
PRTF Reporting: Ensure all communications are properly tracked for compliance