Common Services API (1.31.0-integration.1)

This document is intended for SSG developers who need applications to interact with backend services and data. It explains basic concepts of SchoolStatus and the API itself. It also provides an overview of the different API supported functions.

1. Some way to hit an API endpoint and receive responses. We’re aware that various organizations within SchoolStatus have different technical stacks, and so we advise that you use whatever your preferred library is for API connections.
2. An API Key. For now, these can be requested from the Platform team, but we will move this functionality over to either DevOps or IT management at some point.
3. A phone number to send/receive SMS from - for now, this should come from Twilio, but we will add support for other providers in the future.
4. A callback URL - somewhere we can send updates and information about inbound messages to.
5. Familiarize yourself with the core concepts of the JSON (JavaScript Object Notation) data format. JSON is a common, language-independent data format that provides a simple text representation of arbitrary data structures.

This Quickstart will teach you how to do send and recieve text and calls using the Contact Channel API. In this Quickstart, you will learn how to:

1. Get an API Key to Authenticate with Shunkan-Ido
2. Set up your development environment to send and receive messages
3. Send your first SMS
4. Receive inbound text messages
5. Reply to incoming messages with an SMS
6. Start your first call.

You can find all this at Platform Wiki.

1.31.0-integration.1 (2025-01-14)

Features

• add announcements webhook documentation (2b6e60e)
• add smstool message characters counting enhancement (a4d0b5a)
• dashboard: calls and conference calls stats (e7dfacf)
• dashboard: calls and conference calls stats (8d0cb28)
• deliver unknown participant message COMM-779 (f902601)
• fix bug with inbound messages and calls (2b9cdcf)
• handle block and unblock for inbound announcements (ff8e034)
• handle lookup errors with internal_status and send notification (3a35588)
• provision announcement numbers automatically (COMM-974) (c4ff150)
• refactor participant and conversation repositories (d592460)
• refactor twilio number migration (COMM-838) (c2accc4)
• refs #comm-1033 update to latest datadog gem (a413b40), closes #comm-1033
• refs #comm-937 check for unique client conversation ID and application name (3d01a05), closes #comm-937
• refs #comms-973 Add E164 validation for phone number on message create endpoint (57a9eba), closes #comms-973

Bug Fixes

• add missing index to receiver_number in messages (d1366f2)
• announcements: filter recipients before inserting in batches to make the list uniq (d0a521b)
• COM-1005 remove e164 validation error (07d774b)
• refs #comm-1033 fix requirement statement (de9298d)

1.31.0-integration.1 (2025-01-14)

Features

• add announcements webhook documentation (2b6e60e)
• add smstool message characters counting enhancement (a4d0b5a)
• dashboard: calls and conference calls stats (e7dfacf)
• dashboard: calls and conference calls stats (8d0cb28)
• deliver unknown participant message COMM-779 (f902601)
• fix bug with inbound messages and calls (2b9cdcf)
• handle block and unblock for inbound announcements (ff8e034)
• handle lookup errors with internal_status and send notification (3a35588)
• provision announcement numbers automatically (COMM-974) (c4ff150)
• refactor participant and conversation repositories (d592460)
• refactor twilio number migration (COMM-838) (c2accc4)
• refs #comm-1033 update to latest datadog gem (a413b40), closes #comm-1033
• refs #comm-937 check for unique client conversation ID and application name (3d01a05), closes #comm-937
• refs #comms-973 Add E164 validation for phone number on message create endpoint (57a9eba), closes #comms-973

Bug Fixes

• add missing index to receiver_number in messages (d1366f2)
• announcements: filter recipients before inserting in batches to make the list uniq (d0a521b)
• COM-1005 remove e164 validation error (07d774b)
• refs #comm-1033 fix requirement statement (de9298d)

1.30.2 (2025-01-13)

Bug Fixes

• uniq list of recipients before inserting when enqueuing mms (780784c)

1.30.1 (2025-01-10)

Bug Fixes

• add missing index to receiver_number in messages (cf7286d)
• apply specifif filters to recipients (b988315)

1.30.0 (2025-01-09)

Features

• add TwilioWebhookUpdate consumer handler (796dca9)

1.29.0 (2025-01-08)

Features

• add announcement_number flag to twilio numbers in active admin (COMM-950) (57657c8)
• announcements: provision announcement numbers manually in activeadmin (COMM-950) (e4b61ef)

Bug Fixes

• provider_number panel (bd9ca1d)

1.28.0 (2025-01-07)

Features

• handle lookup errors with internal_status and send notification (c65bd82)

1.27.0 (2024-12-18)

Features

• Update to latest datadog gem. We updated to version 2.8 so that we can get profile allocation data in DataDog. (bbc16c5)

1.26.0 (2024-12-13)

Features

• add announcements webhook documentation (5acc77a)
• handle block and unblock for inbound announcements (e25afce)

1.25.1 (2024-12-11)

Bug Fixes

• COM-1005 remove e164 validation error (648e927)

1.25.0 (2024-12-10)

Features

• add conversations associations aa view (d2cb6b8)
• add participant associations aa view (04223a3)
• add webhooks associations aa view (bb289f4)
• video_calls: add association panels for video call participants in activeadmin (f40b048)
• video_calls: add association panels for video calls in activeadmin (070b97a)

1.24.0 (2024-12-09)

Features

• add calls associations aa view (2c41b96)
• add conference_calls associations aa view (6e92501)
• add messages associations aa view (e583e2d)
• add voicemail associations aa view (ead2ac1)
• dashboard: calls and conference calls stats (6125d8e)
• deliver unknown participant message COMM-779 (5b7e83b)

1.23.0 (2024-12-04)

Features

• [COMMS-973] Add E.164 validation to receiver numbers for messages (8f5f340)
• announcement message custom filters in activeadmin (e664bc2)
• announcements: handle incoming webhooks for voice and sms announcements refs:COMM-921 (3e4797d)
• announcements: improve API request documentation (bb74f4f)

Bug Fixes

• [COMM-935] eliminate machine detection on non-moderator calls to solve endless hold music problem (6521f97)
• errors without translation are confusing clients (93ad9e9)
• phone voice service twiml response and callback url (6e90d0c)

1.24.0 (2024-12-04)

Features

• announcement message custom filters in activeadmin (e664bc2)
• announcements: handle incoming webhooks for voice and sms announcements refs:COMM-921 (3e4797d)
• announcements: improve API request documentation (bb74f4f)

Bug Fixes

• phone voice service twiml response and callback url (6e90d0c)

1.23.0 (2024-12-04)

Features

• [COMMS-973] Add E.164 validation to receiver numbers for messages (8f5f340)

Bug Fixes

• [COMM-935] eliminate machine detection on non-moderator calls to solve endless hold music problem (6521f97)

1.22.0 (2024-11-21)

Features

• COMM-937 Validate that the client_conversation_id and application_name combination is unique (b3b5256)

1.21.0 (2024-11-19)

Features

• Add Twilio MessagingService SID prefix validations (58e7021)
• announcements: deliver sms announcement (91a88cc)
• announcements: deliver voice announcement (6defeed)
• fix bug with new models (eaafed9)
• refactor participant and conversation repositories (fc9287a)

Bug Fixes

• dashboard duration column (c4c5f0c)
• typo in method call for creating customers (f1d2f4c)

1.20.1 (2024-11-14)

Bug Fixes

• typo in method call for creating customers (f1d2f4c)

1.20.1 (2024-11-14)

Bug Fixes

• typo in method call for creating customers (f1d2f4c)

1.20.0 (2024-11-14)

Features

• new announcements feature payloads input/output (cd919c8)
• refs #comm-909 add announcements to activeadmin views (4da2adf), closes #comm-909
• refs #comm-909 add recipient activeadmin view (24a9299), closes #comm-909
• refs #comm-910 only use non-announcement numbers in magic source (cbf0ac3), closes #comm-910
• refs #comm-910 update announcement number from ActiveAdmin (8d4797e), closes #comm-910

Bug Fixes

• #comm-910 fix broken spec (6277523)

1.19.0 (2024-11-12)

Features

• customize active admin authentication logic to ignore devise and use one login COMM-450 (cfe0a71)

1.18.1 (2024-11-07)

Bug Fixes

• check for blocked status on scheduled messaging refs COMM-894 (802f070)

1.18.0 (2024-11-07)

Features

• messages dashboard (e454467)

1.17.0 (2024-11-01)

Features

• Add HighPriorityDeliverSmsConsumer and virtual partitions config (ae64115)
• Add priority attribute to Messages (9cac02d)

1.16.0 (2024-10-31)

Features

• allow delete and update TwilioNumber in AA (1980d95)

1.15.1 (2024-10-30)

Bug Fixes

• fix duplicate webhooks ref COMM-870 (6103205)
• fix webhook payload and statuses ref COMM-870 (45ee541)
• fix webhooks admin page ref COMM-870 (dbae302)
• remove debugging helper ref COMM-870 (7674710)

1.15.0 (2024-10-24)

Features

• alter incoming calling menu (f1179f6)

Bug Fixes

• video_calls: video Call Domain Action End is trying to end a call that is already expired (408b17b)

1.14.0 (2024-10-09)

Features

• Add mock-twilio gem 1.0.0 (1372e68)
• Add mock-twilio integration status endpoints (889e895)
• Add mock-twilio integration toggle (02d8614)
• Add Switchable mock and real data (3e8afe5)
• adding credentials for one login production env (2fd96ff)
• adding one login credentials for staging environment (cd9bd48)
• set up mock schema data (07cf4d2)

Bug Fixes

• move tables from common_services to public schema (6bd842d)

1.13.0 (2024-10-01)

Features

• add get endpoint for video calls refs COMM-833 (399c9a2)
• verify all api specs are documented COMM-849 (bdf3699)

1.12.0 (2024-09-26)

Features

• expose new fields business_profile_sid & shaken_stir_product_si… (#423) (cb99065)

Bug Fixes

• fix video call webhook type typo refs COMM-832 (8814830)

1.11.1 (2024-09-19)

Bug Fixes

• remove undocumented direct_calls webhook refs COMM-801 (#410) (cd410f4)

1.11.0 (2024-09-19)

Features

• messaging_services: Move twilio numbers related with a customer to (#383) (1696ee1)

Bug Fixes

• migration for customers dedicated (e713b1c)

1.10.0 (2024-09-16)

Features

• add match state validation for customer save (#407) (61ccc9a)

1.9.0 (2024-09-10)

Features

• add automatic machine detection result as attribute on calls object refs COMM-525 (#401) (a62facf)
• Add staging to recordings CF url formation (#385) (cd53c75)
• Set new integration DB (#397) (228b3e5)
• set state code in phone numbers refs: #COMM-803 (#399) (1c81fb9)
• shunkan ido translation of classic number pairings COMM-743 (#386) (97fa42a)

Bug Fixes

• create failed webhook dead letter queue topic as disabled (#402) (cf650d4)
• inconsistent phone numbers for customers (#403) (ccc5090)
• move tables from common_services to public schema (#404) (73daee5)

1.8.0 (2024-08-26)

Features

• Add classtag domain callback_url migration to connect url (#382) (ca4400f)
• fetch numbers from state related with messaging service k12 (#394) (7e74d6a)
• refs #comm-752 enforce maximum call length (#376) (243e2c2)
• rexml CVE-2024-43398 (#396) (5e22106)
• use tick to execute scheduled tasks refs: #COMM-772 (#390) (b6c7058)

Bug Fixes

• fix machine detection #ref COMM-496 (#364) (75ed42e)

1.7.0 (2024-08-16)

Features

• adding new end point to receive webhook request from lambda fun… (#368) (32fdc4a)
• comm-441 Video Call Recording functionality (#299) (0fc253a)
• refs #comm-753 handle session key parameter when creating video call participant (#371) (5568289)
• update docker-compose to enable external access to local kafka cluster (#378) (8b733c9)

Bug Fixes

• refs #comm-721 fixes for video call recording lambda code (#372) (9eb15a7)
• refs #comm-744 add environment variable for updated playright automation (#381) (965a5c8)

1.6.0 (2024-07-25)

Features

• Add virtual_host option s3 recordings url formation (#365) (6150387)
• db structure for customers table and K-12 refs: COMM-722 (#366) (4caadea)
• fix message_body string OPT_OUT case-insensitive (#367) (44f6621)
• refs #comm-616 add caller ID to voicemail webhooks (#361) (cc2a162)
• upgrade twilio-ruby and mock-twilio (#363) (b53ef77)

1.5.0 (2024-06-24)

Features

• add mock twilio gem (#353) (57e9c01)
• add mock-twilio 0.2.0 - Webhooks::Messages.trigger (#354) (57b8f56)
• add Mock::Twilio::Client (#348) (57e9c01)
• refs: #comm-546 automatically sync twilio numbers (#342) (0ed868e)
• save error_code and set error_description from webhook updates in messages refs: #COMM-566 (#350) (e1fb127)
• switch to mms type if sms > 160 characters refs: #COMM-594 (#359) (24db97b)

Bug Fixes

• refs #comm-586 use correct bucket name for recording downloads (#358) (dbda2f5)
• refs #comm-617 change call create to use participant twilio number (#356) (8415d09)

1.4.0 (2024-05-21)

Features

• add docker compose, prism set up for twilio mock endpoints (#345) (9313b60)

Bug Fixes

• force mms type sending empty array of media files to twilio (#346) (9aaf82d)

1.3.0 (2024-05-20)

Features

• refs #comm-550 edit conversation by client_conversation_id (#343) (282d715)
• refs #comm-550 edit conversation by global_id (282d715)
• refs #comm-550 edit conversation by internal_conversation_id (282d715)
• refs comm-517 change default welcome message (#335) (a572b3f)
• remove 160 characters validation for SMS body refs: #COMM-558 (#344) (18ce239)

Bug Fixes

• refs #comm-545 db migration to add missing twilio numbers to production db (#341) (2c1104f)

1.2.2 (2024-05-09)

Bug Fixes

• refs #comm-506 additional validations for message creation (#325) (e9671f9)

1.2.1 (2024-05-06)

Bug Fixes

• refs #comm-492 fix: create voicemail records on webhook (151d3b0)

1.2.0 (2024-05-03)

Features

• add changelog from the github release action to the API doc (#327) (6bccfb0)
• add version.txt (8e7216a)
• notify consumer errors to bugsnag (#326) (59c0f60)
• refs #COMM-414 add callback_url webhooks on zoom events (#295) (2bf2772)

Bug Fixes

• pages run after release (51025ba)
• Slow SMS Delivery (#319) (dc8e339)

Reverts

• Znensey/fix/comm 500 move prod back to redpanda brokers (#320) (836d312)

1.1.0 (2024-04-25)

Features

• adds the ability to play a welcome message to call participants on a conference call (53bc624)
• comm-412 zoom webhook handler (#288) (9eeb5d0)
• comm-436 welcome messages for conference calling. (#292) (53bc624)
• document callback_url logic refs: #COMM-483 (#315) (a2abef4)
• github release action using release-please-action refs: #COMM-489 (1e2b637)
• github release action using release-please-action refs: #COMM-489 (d2a9fcf)
• implement get endpoint for D2P call recording by providing the Call UUID refs: #COMM-455 (#296) (5872637)
• Improve transcription documentation refs: #COMM-443 (#302) (0aea719)
• refactor documentation for conference calls and direct calls in swagger refs: #COMM-460 (#306) (c0331c0)
• refs #comm-434 configurable welcome message for direct calls (#287) (8cfc2ae)
• refs #comm-458 messaging service endpoints (#300) (830135f)
• refs #comm-463 add data migration to delete data in local/integ… (#304) (6d5cdc4)
• save webhook payload in DB and show in activeadmin refs: #COMM-431 (826c768)
• save webhook payload in DB and show in activeadmin refs: #COMM-431 (#289) (826c768)

Bug Fixes

• blueprint response in webhooks (#308) (2d716c0)
• move misplaced json doc file. (#297) (141fe7b)
• name validation in messaging service blocking deployments (d720c67)
• skip callbacks in messaging service name migration (7450895)
• vertical scroll in webhook payload refs: #COMM-440 (826c768)

The Common Services API uses Bearer Token authentication for authorization of requests. These tokens need to be supplied - otherwise the API will return a 403 Forbidden error. For more details on all that, please refer to the Platform API Overview.

The Common Services API implements two objects, both of which are required for API Access: a Bearer Token and an API Key. A single bearer can have multiple API keys if desired.

There are two user levels for actions relating to API keys. Actions can be performed as an admin or user. Actions taken as an admin can be performed regardless of associated bearers. Non-admin actions can only be performed for the associated bearer token(s).

Bearers can only be generated by someone with admin level API Access. If a user or application sends an outbound message, Common Services will process the message, send it out through our provider, and then receive webhook updates from the provider. Supplying this URL is required for the original application to receive updates regarding the message that was sent out.

Separately, if an inbound message comes in, this URL can also be used to send notifications to an application that a message has been received.

All of this fields are required for generating a bearer.

The Conference Calls object represents a single attempt to create a call between two or more phones.

A conversation is a unique message thread that contains Participants and the Messages they have sent.

The Messages object represents an inbound or outbound message between a school entity and one or more guardians. You can create a message object via the REST API, and a message object is created when someone sends a message to a sender_number. Use it to send or schedule a new message, to retrieve a specific message, cancle a scheduled message, or retrieve a list of messages.

The SDK calls resource allows you to generate a Twilio voice-token (also called AccessToken in Twilio documentation) for calls and TwiML responses using the Twilio frontend calling SDKs.

The Return Calling feature encompasses two main scenarios:

1. Return Calling via SDK Phone: This scenario caters to calls made using the Twilio SDK by a school staff member to a contact.
2. Return Calling via Phone-to-SDK: This scenario applies to calls made by a contact to a school staff member.

Each scenario provides callers with menu options upon returning a call, including reconnecting with the teacher, leaving a voicemail, or opting out of future calls.

Enable parents to return calls made by teachers, offering them specific interaction options.

1. Device Initialization: The school staff member will need to have a device registered with Platform and Twilio before any calls can be forwarded to it. Depending on your implementation of the Twilio SDK, this will most likely only be the case if the teacher has made a call using their browser.
2. Play Call Menu Options: Platform will play back the call menu options to the parent. If they select 'option 1' then Platform will instruct Twilio to forward the call through to the Twilio SDK software phone belonging to the school staff member.
3. Detect Return Call: The Twilio SDK will receive the call from Twilio and ring the staff member.
4. No Device Available: If there is no device initialized for the staff member the contact is trying to call, then 'option 1' will automatically route them to leave a voicemail.
5. Retrieve Voicemail: Once the voicemail has been recorded and the call has ended, the recording is processed and transcribed. Once this process is completed, a callback containing a URL to the artifacts in its payload, will be sent to your webhook URL. This URL will be good for 24 hours. A request to GET {host}/api/v1/voicemails/{id} can be used to retrieve a new signed URL.

Retrieves a status check for the health of the Common Services API resources.