The platform known as ServiceNow is a major component to an organization’s overall IT Service Management (ITSM) and workflow automation strategy. ServiceNow, according to its website, is “the intelligent platform for business transformation” — delivering end-to-end workflow automation across IT, HR, customer service, and operations. This really means that the product is the key incident management and process automation component to an organization’s broader digital operations offering. The platform can trigger notifications, escalate tickets, send approval requests, and route communications across channels while tracking their effectiveness through real-time dashboards and reporting.

This tutorial will focus on how ServiceNow can be leveraged to send out SMS messages with the assistance of RingCentral.

Before you get started, please ensure the numbers you plan to send SMS from are registered under the appropriate TCR Campaign in the RingCentral Admin Portal. To send automated or marketing messages, these numbers must be assigned to an “Automated” campaign type. You cannot use a conversational campaign to send automated or marketing messages.

Step 1: Set up JWT token

In the RingCentral Developer platform you can create your JWT Key for use with the RingCentral Labs Marketo SMS App. Through the Marketo SMS App you will be able to use Marketo webhooks to connect to the RingCentral SMS APIs. Please note, this app is in beta and is not officially supported by RingCentral.

Once you have signed in to the platform, follow these steps:

1. Click on your profile name to access the pull-down menu. Click on “Credentials” as shown in figure 1.

2. Click “Create JWT” which will bring up the following screen:

Press enter or click to view image in full size

3. Create a name or label for this JWT that will help you recognize what this token is for in the future, and enter it in the Label field.

4. Under environment, ensure Production is selected

5. For what apps are permitted to use this credential, check “Only specific apps of my choice.” You will then be prompted for a Client ID.

Press enter or click to view image in full size

6. Enter “fKZNy9WuNShd7aQcu6Z2sj” as the client ID and click Add App. You should now see “Marketo SMS App” listed as an authorized app for this client ID.

7. Choose an expiration date or leave blank. If you enter an expiration date, your token will stop working after this time, and you will need to create a new token before the expiration or you will not be able to send SMS through the Marketo SMS App API.

8. Click create JWT. You should now see your credentials screen.

9. Click the copy icon next to your JWT to get the full JWT code.

Setting up ServiceNow

ServiceNow uses a concept called REST Messages to integrate with outside applications like RingCentral. In ServiceNow, find the link called “REST Message” under the Outbound section, which is found within the System Web Services module in the left-hand navigation menu. Create a new REST Message and name it appropriately.

Now open the created record, and in the HTTP Methods related list, click New and select the HTTP method as POST.

Enter the following information:

Endpoint: https://marketo.apps.gamechanging.dev/api/sms

Content: jwt=JWT_TOKEN&fromNumber=${from}&toNumber=${to}&type=standard&text=${text}

Content-type: application/json

Important: Replace JWT_TOKEN with the JWT Token you generated in Step 1. You may also save it as a variable in ServiceNow. Ensure that ${from} is a SMS registered RingCentral phone number tied to your extension.

You should now be able to utilize RingCentral within ServiceNow to send SMS messages using ServiceNow REST Messages.

Automating SMS in ServiceNow was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Video meetings are full of decisions, action items, deadlines, and customer commitments. The problem is that most teams still rely on manual note taking and human memory to create follow ups after the meeting ends.

That creates delays, inconsistent communication, and often missed tasks.

With RingCentral’s communication platform APIs and its set of AI-specific APIs, developers can automate much of this workflow using real meeting recordings, AI-generated summaries, and messaging integrations.

Instead of manually reviewing the recording of a lengthy meeting, your application can automatically:

• retrieve meeting or call insights
• extract action items
• generate customer follow up emails
• send internal team notifications
• create CRM tasks
• archive meeting intelligence

This article walks through a practical PHP implementation using currently documented RingCentral APIs and SDK syntax.

The workflow we will build could look like this:

1. A RingCentral video meeting
2. RingCentral generates recordings and AI insights
3. Your application retrieves the insights
4. PHP code processes the summaries and action items
5. Automated follow ups are generated and delivered

The APIs Used

This workflow will make use of a few different RingCentral platform capabilities:

• Call Log API — Detect completed video calls and recordings
• Webhooks — Receive real-time event notifications
• Call Recording API — Access video recording metadata and media
• RingSense / AI Conversation Expert API — Retrieve summaries, transcripts, highlights, and action items

Required Application Scopes

Your RingCentral application must request the proper OAuth scopes depending on which endpoints are used.

• ReadCallLog — Read call and meeting records
• ReadCallRecording — Access recordings metadata and content
• WebhookSubscriptions — Create Webhook subscriptions
• SMS — if you intend to disseminate video call summaries by text
• Team Messaging — if you intend to disseminate video call summaries by Team Messaging means
• Fax — if you intend to disseminate video call summaries by fax

Understanding What the AI Integration Provides

RingCentral AI capabilities are exposed through features like voice recordings, transcripts, and summaries generated from recorded call meetings. These artifacts become available soon after a conference call ends and can be accessed through the platform’s insights API endpoint.

In practice, this means your workflow will combine:

• meeting lifecycle events via the Notifications API
• call recording and meeting data via the REST API
• your own logic to distribute follow ups

Let’s look at the steps involved in a concrete use case. After a video meeting is recorded, with transcription and notes turned on, your system should get a notification that a video call event has occurred. From there, your application can retrieve the call’s recording and metadata, extract the call’s available transcript or summary data, and send follow up communication to participants.

Instead of polling for completed video calls, you can subscribe to an RCV (RingCentral Video) event and react in real time. Before this notification functionality is active however you need to have a few things in place.

1. Your RingCentral account (phone number) should have the “AI Conversation Expert” licence active on it (there is an additional fee for this service). See the following image showing how this is established within the Service Web interface.

2. You need to have a RingCentral developer app (REST JWT) with the following scopes attached to it:

Call Control
Read Call Log
Read Call Recording
RingSense
SMS
Webhook Subscriptions

You will need even more app scopes active if you plan to send call follow-up information messages by fax or Team Messaging, for example.

Setting Up Event Subscriptions

To detect when a video call’s transcription information is available you can subscribe to /rcv/insights events. You do this by creating a webhook that “listens” for these events. The RingCentral API platform will watch for an event that indicates when the video call or session transcription information is available.

Here is how to create a subscription using the RingCentral PHP SDK. After you connect to the SDK ($platform) you create the subscription with the post method passing it the needed credentials.

try {
 $api_call = $platform->post('/subscription',
 array(
 "eventFilters" => array('/ai/ringsense/v1/public/accounts/~/domains/rcv/insights',),
 "expiresIn" => "315360000",
 "deliveryMode" => array(
 "transportType" => "WebHook",
 // need full URL for this to work as well
 "address" => $subscription_url,
 )
 )
 );
 $webhook_id = $api_call->json()->id;
 echo_spaces("Webhook ID", $webhook_id);
} catch (\RingCentral\SDK\Http\ApiException $e) {
 echo_spaces("create_webhook API Exception", $e->getMessage(), 2);
 exit();
}

This registers your application to receive updates about session state changes and in our sample code we display the newly created webhook (subscription) id.

When the Webhook is Triggered

Once established, the webhook will react when a suitable event occurs. In this case, as mentioned, when the video call’s transcription information is ready for use. When the event is triggered the payload of that event is sent to the URL address that you provided when it was created, “address” => $subscription_url,. After it passes some necessary validation we get the event information payload and optionally save it to the server (received_Video_EVENT_payload.log) for later debugging, if needed.

$hvt = isset($_SERVER['HTTP_VALIDATION_TOKEN']) ? $_SERVER['HTTP_VALIDATION_TOKEN'] : '';
if (strlen($hvt) > 0) {
header("Validation-Token: {$hvt}");
}
$incoming = file_get_contents("php://input");
// if desired, also save the incoming event information to
// a local file for human viewing
file_put_contents("received_Video_EVENT_payload.log", $incoming);
if (empty($incoming)) {
http_response_code(200);
// echo json_encode(array('responseType' => 'error', 'responseDescription' => 'No data provided Check Event payload.'));
echo_spaces("No video data payload received Check Event payload.");
exit();
}
$incoming_event_data = json_decode($incoming, true);
if (!$incoming_event_data) {
http_response_code(200);
 echo_spaces("Media type not supported. Please use JSON.", "", 2);
 exit();
}

The event payload would be one continuous string that could look like this:

After this step, our code then extracts the information that we need to get the details from the API. The remaining code follows. After we break down the incoming data object to its respective event information we connect to the SDK and test each event to see if the call has a “Disconnected” status, this means that the call is completed and the AI insights should be available. It can actually take some time to assemble the insights information depending on how long the call was and how busy the servers are at the time. You may want to wait a few minutes after the event is triggered before you collect the call transcript and other information to ensure it is all there. Assuming all the event insights are ready for us we then collect the call log information with a get method call to the call-log endpoint based on the sessionId and from that response object we can get the call details.

$controller = ringcentral_sdk();
$platform = $controller['platform'];
//echo_spaces("incoming EVENTS", $incoming_event_data, 2);
echo_spaces("Call Title", $incoming_event_data['body']['title'], 1);
foreach ($incoming_event_data['body']['speakerInfo'] as $speaker) {
 echo_spaces("Speaker Name", $speaker['name']);
}
echo_spaces("", "", 1);
foreach ($incoming_event_data['body']['insights']['Transcript'] as $segment) {
 echo_spaces("Transcript segment", $segment['text']);
}
echo_spaces("", "", 1);
echo_spaces("Call Summary", $incoming_event_data['body']['insights']['Summary'][0]['value'], 1);

If you want to see the whole call log object structure ($incoming_event_data), you can output it in a similar way to the code that is commented out on the third line in the above section of code.

I am sending some of the event payload information to the output stream so that I can see what is going on with my code, but typically the processing of webhook events is non-visual. I can see the output when I run my code through a service like postman (postman.com). Following is an image showing what the output looks like.

You can then use any or all of the transcribed information available to you to send out call summary SMS messages, Team Messaging group notes, and even Faxes if you so wish.

Closing Thoughts

Automating video call follow ups is a natural extension of event-driven architecture. RingCentral provides the building blocks through its Notifications API, call log endpoints, and recording resources. AI-generated transcripts and insights add an additional layer of value to the communications process.

By combining these powerful API pieces, you can build a workflow that ensures every call meeting is followed up by timely, consistent communication without needing time consuming manual processes.

Automating Video Call Follow Ups Using the RingCentral AI Integration API was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Conference call meeting follow ups are one of those tasks that everyone agrees are important, but because it is often very manual “busy work”, follow ups are often delayed or skipped entirely. Call notes get buried, action items are forgotten, and momentum fades quickly after a call ends.

With RingCentral’s AI-powered meeting insights and the existing platform APIs, you can automate much of this workflow. The goal is not to replace human judgment, but to ensure that summaries, recordings, and key outputs are delivered consistently and promptly after a meeting.

This article walks through how to build a practical follow up system using RingCentral APIs, webhook notifications, and the PHP SDK.

Understanding What the AI Integration Provides

RingCentral AI capabilities are exposed through features like voice recordings, transcripts, and summaries generated from recorded call meetings. These artifacts become available after a conference call ends and can be accessed through the platform’s insights API endpoint.

In practice, this means your workflow will combine:

• meeting lifecycle events via the Notifications API
• call recording and meeting data via the REST API
• your own logic to distribute follow ups

Let’s look at the steps involved in a concrete use case.

After a voice call meeting is recorded with transcription and notes turned on, your system should:

• detect that the call has ended
• retrieve the recording and metadata
• extract available transcript or summary data
• send a follow up communication message to participants

Instead of polling for completed calls, you can subscribe to telephony events and react in real time. Before this is active however you need to have a few things in place.

1. Your RingCentral account (phone number) should have the “AI Conversation Expert” licence active on it (there is an additional fee for this service). See the following image showing how this is established within the Service Web interface.

2. You need to have a RingCentral developer app (REST JWT) with the following scopes attached to it.
a) Call Control
b) Read Call Log
c) Read Call Recording
d) RingSense
e) SMS
f) Webhook Subscriptions

You will need more app scopes active if you plan to send call followup information messages by fax or Team Messaging, for example.

Setting Up Event Subscriptions

To detect when a call session ends, you can subscribe to telephony session events. You do this by creating a webhook that “listens” for these events. We watch for an event that indicates when a call or session changes state.

Here is how to create a subscription using the RingCentral PHP SDK. After you connect to the SDK ($platform) you create the subscription with the post method passing it the needed credentials.

try {
$api_call = $platform->post('/subscription',
array(
"eventFilters" => array(
'/restapi/v1.0/account/~/telephony/sessions',
),
"expiresIn" => "315360000",
"deliveryMode" => array(
"transportType" => "WebHook",
// need full URL for this to work as well
"address" => $subscription_url,
)
)
);
$webhook_id = $api_call->json()->id;
echo_spaces("Webhook ID", $webhook_id);
} catch (\RingCentral\SDK\Http\ApiException $e) {
echo_spaces("create_webhook API Exception", $e->getMessage());
exit();
}

This registers your application to receive updates about session state changes and in our sample code we display the newly created webhook (subscription) id.

When the Webhook is Triggered

Once established, the webhook will react when a suitable event occurs. In this case when a telephony event happens. When the event is triggered the payload of that event is sent to the URL address that you provided when it was created, “address” => $subscription_url. After it passes some necessary validation we get the event information payload and optionally save it to the server (received_EVENT_payload.log) for later debugging, if needed.

$hvt = isset($_SERVER['HTTP_VALIDATION_TOKEN']) ? $_SERVER['HTTP_VALIDATION_TOKEN'] : '';
if (strlen($hvt) > 0) {
header("Validation-Token: {$hvt}");
}
$incoming = file_get_contents("php://input");
// if desired, also save the incoming event information to
// a local file for human viewing
file_put_contents("received_EVENT_payload.log", $incoming);
if (empty($incoming)) {
http_response_code(200);
echo json_encode(array('responseType' => 'error', 'responseDescription' => 'No data provided Check Event payload.'));
exit();
}
$incoming_event_data = json_decode($incoming, true);
if (!$incoming_event_data) {
http_response_code(200);
echo json_encode(array('responseType' => 'error', 'responseDescription' => 'Media type not supported. Please use JSON.'));
exit();
}

The event payload would be one continuous string that could look like this:

{"uuid":"6975102786429086013","event":"/restapi/v1.0/account/3058829020/
telephony/sessions","timestamp":"2026–04–27T18:45:22.168Z","subscriptionId"
:"2ff48c00–6c78–4ef5–8eb4–1a269ff1e616","ownerId":"2412476021","body":
{"sequence":11,"sessionId":"6326XXX6020","telephonySessionId":
"s-a0d16e911f939z19dd04137ffz2432460000","serverId":"10.13.22.233.TAM",
"eventTime":"2026–04–27T18:45:22.070Z","parties":[{"accountId":"30588XXX20",
"id":"p-a0d16e911f939zXXXfz2432460000–1","direction":"Outbound","to":
{"phoneNumber":"+190XXX774","name":"Peter Beck MacIntyre","extensionId"
:"241XXX21"}, "from":{"phoneNumber":"+190XXX5827","name":"CHARLOTTETOW PE"},
"status":{"code":"Disconnected", "rcc":false},"park":{},"missedCall":false,
"standAlone":false,"muted":false}],"origin":{"type":"Call"}}}

I have added “XXX” to some of the listed information above for security reasons. After this step, our code then extracts the information that we need to get the details from the API. The remaining code follows. After we break down the incoming data object to its respective event information we connect to the SDK and test each event to see if the call has a “Disconnected” status, this means that the call is completed and the AI insights should be available. It can actually take some time to assemble the insights information depending on how long the call was and how busy the servers are at the time. You may want to wait a few minutes after the event is triggered before you collect the call transcript and other information to ensure it is all there. Assuming all the event insights are ready for us we then collect the call log information with a get method call to the call-log endpoint based on the sessionId and from that response object we can get the call details.

$controller = ringcentral_sdk();
$platform = $controller['platform'];
if (isset($incoming_event_data['body']['parties'])) {
foreach ($incoming_event_data['body']['parties'] as $party) {
if ($party['status']['code'] == "Disconnected") {
echo_spaces("Session ID", $incoming_event_data['body']['sessionId']);
echo_spaces("Call status", $party['status']['code']);
$apiResponse = $platform->get('/restapi/v1.0/account/~/call-log', [
'sessionId' => $incoming_event_data['body']['sessionId']
]);
$callLog = $apiResponse->json();
echo_spaces("Recording ID", $callLog->records[0]->recording->id, 1);
echo_spaces("Recording ContentURI", $callLog->records[0]->recording->uri, 1);
$recordingId = $callLog->records[0]->recording->id;
// echo_spaces("call log deets", $callLog);

If you want to see the whole call log object structure you can output it in a similar way to the code line above.

The next section of code takes the recording id and accesses the transcription information from the “ai… insights” end point.

try {
$endpoint = '/ai/ringsense/v1/public/accounts/~/domains/pbx/records/' . $recordingId . '/insights';
$resp = $platform->get($endpoint);
$insightsObj = $resp->json();
//echo_spaces("Recording insights", $insightsObj, 1);
$attendeeCount = 1;
// cycle through the list of call attendees adding a counter to the output
foreach ($insightsObj->speakerInfo as $attendees) {
echo_spaces("Call attendee $attendeeCount", $attendees->name);
$attendeeCount++;
}
echo_spaces("", "", 1);
echo_spaces("Call Summary", $insightsObj->insights->Summary[0]->value, 1);
echo_spaces("Call Notes and recap", $insightsObj->insights->CallNotes[0]->value, 1);
} catch (ApiException $e) {
print 'Expected HTTP Error: ' . $e->getMessage() . PHP_EOL;
}
}
}
}

I occasionally send some information to the output stream so that I can see what is going on with my code, but typically the processing of webhook events is non-visual. I can see the output when I run my code through a service like postman (postman.com). Following is an image showing what the output looks like.

If you want to see the whole insights AI object content, then use a similar line of code to this one: echo_spaces(“Recording insights”, $insightsObj, 1);

This will list the object structure similar to the following and you can use that to extract any of the AI generated content relating to a particular call. Here is what a partial listing could look like as generated from within postman.

You can then use any or all of the transcribed information available to you to send out call summary SMS messages, Team Messaging group notes, and even Faxes if you so wish.

Closing Thoughts

Automating conference call follow ups is a natural extension of event-driven architecture. RingCentral provides the building blocks through its Notifications API, call log endpoints, and recording resources. AI-generated transcripts and insights add an additional layer of value to the communications process. In a future article I will show you how to get similar information from video meetings so stay tuned.

By combining these powerful API pieces, you can build a workflow that ensures every call meeting is followed up by timely, consistent communication without needing time consuming manual processes.

Automating Conference Call Follow Ups Using the RingCentral AI Integration API was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Billing workflows are rarely real time by default. Most systems rely on scheduled jobs or periodic polling to detect events like new invoices, failed payments, or overdue balances. That approach works, but it introduces latency and unnecessary API calls.

RingCentral’s Notifications API provides a cleaner pattern. Instead of polling, your application can subscribe to events and react as they happen. In this article, we will walk through how to use webhook-based subscriptions with the RingCentral PHP SDK to build a simple but realistic billing notification system. We will focus on a practical flow that you can adapt to your own system.

Understanding the Notifications API

At its core, the RingCentral Notifications API is built around subscriptions. A subscription defines:

• which events you care about
• how those events should be delivered

Delivery can happen via WebHooks or WebSockets. For billing-related workflows, WebHooks are usually the better choice because they tend to integrate more naturally with backend systems so we will focus this article on that aspect of the process.

To create a subscription, you send a POST request to the /restapi/v1.0/subscription endpoint with a list of event filters and a delivery mode.

In the PHP SDK, that looks like this:

try {
$api_call = $platform->post('/subscription',
array(
"eventFilters" => array(
"/restapi/v1.0/account/~/extension/~/message-store",
),
"expiresIn" => "315360000",
"deliveryMode" => array(
"transportType" => "WebHook",
// need full URL for this to work as well
"address" => $subscription_url,
)
)
);
$webhook_id = $api_call->json()->id;
echo_spaces("Webhook ID", $webhook_id);
} catch (\RingCentral\SDK\Http\ApiException $e) {
echo_spaces("create_webhook API Exception", $e->getMessage());
exit();
}

This tells RingCentral to push events to your webhook URL address located at $subscription_url whenever relevant activity occurs. We even echo the webhook identifier out to the screen to show that a webhook indeed was created. You may want to add in some controlling code here as well to ensure that you only create one webhook for this purpose for efficiency’s sake.

Note that subscriptions are not permanent “expiresIn” => “315360000”. Granted this is set to expire in approximately 10 years (315360000 seconds), but they do eventually expire and must be renewed periodically, or recreated if they lapse.

While there is no dedicated “billing event” endpoint, billing notifications are typically triggered indirectly through messaging or system-generated alerts. For example:

• SMS alerts for payment failures
• system notifications sent to an extension mailbox
• integrations that convert external billing events into messages

That makes the message store event filter a practical starting point. You will have to look for specific strings in the messaging in order to react appropriately. We will point this out later in our sample code when we process the incoming event information.

A Realistic Billing Notification Flow

Let’s ground this in a real life situation. Imagine you run a magazine subscription service that does the following:

• charges customers monthly
• sends SMS reminders for failed payments
• wants to notify internal staff immediately when a billing issue occurs

Instead of polling for new messages, you can subscribe to message-store events and process them as they occur.

The flow could look like this:

1. Customer payment fails in your billing system
2. Your system sends an SMS via RingCentral
3. RingCentral logs that message in the message store
4. Your webhook receives an event notification
5. Your app parses the message and reacts accordingly

This approach makes your system reactive rather than passive. It can manage events as they occur rather than doing a nightly or weekly process that would have built in latency.

Setting Up the Webhook Endpoint

Before creating a subscription, you need a webhook endpoint that can receive events. You will also need a RingCentral app that is created under your developer account that has the follow scope as a minimum:

• SMS
• Webhook Subscriptions
• Read Messages (not needed if you also have SMS in scope)

You should add in Faxes or Team Messaging if you also plan to send event response notifications to those destinations.

RingCentral requires your webhook to handle a validation handshake. When the subscription is created, RingCentral sends a request with a Validation-Token header. Your server must return that same header to confirm the endpoint.

A minimal PHP webhook processing code example looks like this:

$hvt = isset($_SERVER['HTTP_VALIDATION_TOKEN']) ? $_SERVER['HTTP_VALIDATION_TOKEN'] : '';
if (strlen($hvt) > 0) {
header("Validation-Token: {$hvt}");
}
$incoming = file_get_contents("php://input");
// if desired, also save the incoming event information to 
// a local file for human viewing
file_put_contents("received_EVENT_payload.log", $incoming);
if (empty($incoming)) {
http_response_code(200);
echo json_encode(array('responseType' => 'error', 'responseDescription' => 'No data provided Check Event payload.'));
exit();
}
$incoming_data = json_decode($incoming);
if (!$incoming_data) {
http_response_code(200);
echo json_encode(array('responseType' => 'error', 'responseDescription' => 'Media type not supported. Please use JSON.'));
exit();
}

Once validated, and the content verified we can start processing the event information. The rest of the code could look like this.

// pickup the message id from the event and then get the 
// full message information from the message-store
$messageId = $incoming_data->body->changes['0']->newMessageIds['0'] ;
$controller = ringcentral_sdk();
$platform = $controller['platform'];
try {
$apiResponse = $platform->get("/restapi/v1.0/account/~/extension/~/message-store/$messageId");
$messageDetails = $apiResponse->json();
echo_spaces("Event Message Subject", $messageDetails->subject);
 echo_spaces("Event direction", $messageDetails->direction);
 // you can display the whole object structure this way to see
 // all the other information that you may want to access
 // echo_spaces("Event Message", $event_message);
// Example: detect billing-related SMS
if (strpos($messageDetails->subject, 'Payment failed') !== false) {
// Trigger internal alert(s) as needed.
 // send to TM, SMS, create a fax, etc.
echo_spaces("Event Message", $messageDetails->subject, 1);
}
} catch (\RingCentral\SDK\Http\ApiException $e) {
echo_spaces("Event ERROR Message", $e->getMessage(), 1);
}

In this example all we are doing is sending the message text $messageDetails->subject to the screen for demo purposes. Within that if code segment you can react to the event in any way you wish.

For testing purposes be sure to examine the event payload itself that is saved to the received_EVENT_payload.log file if that line of code is active. Once you open that file it should look something like this structure:

{"uuid":"7653382350236984160","event":"/restapi/v1.0/account/xxxxxx/extension
/xxxxxx/message-store","timestamp":"2026–04–21T18:20:48.180Z","subscriptionId"
:"26a87daa-5066–45b9-b8c4-fcaea228f7f0","ownerId":"62199486016",
"body":{"accountId":xxxxxx,"extensionId":xxxxxx,"lastUpdated":
"2026–04–21T18:20:38.674Z","changes":[{"type":"SMS","newCount":1,
"updatedCount":0,"newMessageIds":[33982xxxx017]}]}}

You can then use that for testing on a site like postman.com and you can echo out data that would normally not show as the processing of the webhook if a non-visual code element. A sample postman screen could look like this.

Processing Billing Notifications

Once events start flowing in, your webhook becomes the decision engine. You can build in other if conditions for the event within the try block and react to other situations like “Credit card expired”, “shipping address not given”, or anything that may be contained within the SMS message.

Closing Thoughts

Automating billing notifications is less about the actual billing itself and more about reacting to events reliably.

RingCentral’s Notifications API gives you a clean, event-driven foundation. By combining webhook subscriptions with message-store events, you can build systems that respond instantly to billing issues without relying on polling or scheduled jobs.

The result is simpler architecture, faster response times, and a better experience for both your team and your customers.

Automating Billing Notifications Using the RingCentral Notifications API was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Spanning the full range of simple automated workflows to large scale integration with agentic AI, APIs are becoming critical to power modern business communications. When you build an app that needs to interact with RingCentral for voice calls, messaging, fax, or SMS (just to name a few of this API’s functions) you must first securely authenticate and authorize it. This guide shows you how to establish authentication and then demonstrates how authorization works with RingCentral’s API. This demonstration will be done with the help of PHP code samples.

With the RingCentral API you could be building a CRM integration that sends SMS updates to customers, an automated voice attendant that places calls based on business rules, or a team messaging dashboard that posts notifications to all members of a chat group. To connect with and use the RingCentral API efficiently, you’ll need a solid understanding of RingCentral’s OAuth 2.0 implementation.

What are authentication and authorization?

While it might seem that these two terms are synonymous, there is a marked difference when it comes to API usage. Authentication means that you verify who (or what) your app is. This means gaining initial access to the API platform by proving that you have legitimate permission to connect to it. Authorization defines what your app is allowed to do on behalf of a user or system after you have authenticated your global access. This defines the scope of what the app is allowed to perform within that platform. This will become more clear as we work through the examples.

It’s important to note that RingCentral uses OAuth 2.0, the industry standard for delegated authorization. This means your app doesn’t store user passwords; it authenticates by exchanging tokens instead.

Prerequisites

Before you begin, make sure you have:

• A RingCentral developer account, obtained here: https://developers.ringcentral.com
• An app registered in the RingCentral Developer Portal
• Your Client ID and Client Secret provided by the app

Use an SDK to connect to the API

The first thing that you need to do is make an authorized connection to the API. This is typically done with the help of an SDK (Software Development Kit) which is a library of code that we install and use to connect to the API. Our code uses the authentication keys that were provided when we created an app on the RingCentral Developer’s site. They are called the Client Id and the Client Secret key. These keys are best stored in an environment file usually called .env. Here is a sample of what we place in that file.

After we install the SDK, the SDK is for PHP in our case, we create a reusable function that will access the .env values to authenticate your code with the API. Remember these codes / keys are directly connected to an app that you create on the RingCentral developers platform and are unique to that app. If you had another app on the platform you would be given different key values. Also, note that in our case when we originally set up the app we chose a JWT style of authentication, which involves another, much longer key that is also generated on the RingCentral developer’s platform. Read this article for details on JWT key creation.

Here is the code that creates a connection to the API. The first three lines give you access to the content of the .env file, then we create the connection to the API through the SDK syntax providing the client id, client secret, and URL path to the API. Since this is a re-usable function we do a quick test to see if we are already logged into the API and if not, we call the login method passing it the JWT value. If all goes well we then return the $controller array which contains a handle to the API

function ringcentral_sdk() {
// Include Libraries
require('includes/vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$jwt_key = $_ENV['RC_JWT_KEY'];
$sdk = new RingCentral\SDK\SDK(
$_ENV['RC_APP_CLIENT_ID'],
$_ENV['RC_APP_CLIENT_SECRET'],
$_ENV['RC_SERVER_URL']);
$platform = $sdk->platform();
// Login via API
if (!$sdk->platform()->loggedIn()) {
try {
$platform->login(["jwt" => $jwt_key]);
} catch (\RingCentral\SDK\Http\ApiException $e) {
$sdk = 0;
// exit("<br/><br/>Unable to authenticate to platform. Check your RingCentral credentials. <br/><br/>") ;
}
}
$controller = array('SDK' => $sdk, 'platform' => $platform);
return $controller;
}

Now that we have authenticated access to the API for a specific app on the RingCentral platform we can perform tasks from within that app. This is where the authorization aspect comes into play. When the app is created you designate what part or parts of the API you want to use. You could be creating an app that sends out both SMS and Fax messages, or you could create an app that only sends content to Team Messenger. These authorizations are also called “Application Scopes”. The good news is that these scopes can be adjusted if you want to change the authorization of the app.

In our sample app here we will just be sending out an SMS message so the scope of the app is quite narrow. The scope in the app then must coincide with what is known as the API endpoint. This means that your code has to direct its request at a specific section of the API. In other words the scope and the endpoint have to match, and this is another aspect to the authorization process. If, as in our example, your app’s scope is for sending SMS messages and we provide an endpoint for sending a fax message then the authorization would fail.

Let’s look at the PHP code for sending an SMS message.

function send_sms($to_mobile, $message) {
$controller = ringcentral_sdk();
$platform = $controller['platform'];
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$from_mobile = $_ENV['RC_MOBILE_SENDING_NUMBER'];
$message .= " Reply STOP to opt out of future communication from this mobile number.";
$api_endpoint = '/restapi/v1.0/account/~/extension/~/sms';
try {
$apiResponse = $platform->post($api_endpoint,
array('from' => array('phoneNumber' => $from_mobile),
'to' => array(array('phoneNumber' => $to_mobile)),
'text' => $message,)
);
} catch (\RingCentral\SDK\Http\ApiException $e) {
// craft a friendly message here.
echo $e->getMessage();
}
}

As you can see, the function starts with calling the SDK connecting function and then connects again to the .env file to pick up the SMS sending phone number. The $to_mobile value is passed into the function along with the text of the outgoing message. We add some boiler plate STOP information to the end of the message text and then set the value of the endpoint where we call the SMS portion of the API. Lastly, we call the post method on the API sending it the parameters that it needs.

To call the sms function you would simply have to use these few lines of code:

$to_number = "+19025551234";
$sms_message = "This is a simple SMS message for you. ";
send_sms($to_number, $sms_message);

We put the post method call within a try/catch structure in case there are issues with the attempt to send the SMS message. For example, we could be using the wrong sending phone number, or the phone number we used does not have permission to send out SMS messages, or the app does not have the scope of sending SMS messages, or in the very rare case, that the RingCentral API is off-line. There could be many issues like this that we need to allow for and we can handle those more gracefully if we want to. See my article on error handling for more details.

Final Thoughts

Authentication and authorization are the foundation of any secure API integration, and RingCentral’s platform is built with that in mind. RingCentral’s APIs use industry-standard authentication protocols and fine-grained authorization controls to ensure that every request is properly verified and scoped. Access tokens, permissions, and secure transport all work together to protect user data and system resources, so developers can build integrations with confidence that security is enforced at every layer of the API stack.

A Guide to Authentication and Authorization with RingCentral APIs was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Imagine you’re building an internal IT helpdesk tool in Python. When a high-priority ticket is created, you want to automatically send an SMS alert to an on-call engineer. Or maybe you’re developing a logistics dashboard that sends delivery status updates to customers.

In both cases, your Python application needs to communicate with the outside world; reliably and in real time. That’s where the RingCentral API comes in.

RingCentral’s platform allows Python applications to send SMS messages, make calls, access call logs, and more. In this guide, we’ll walk through how to integrate RingCentral APIs into a Python application, using the official Python SDK and practical examples. We will be sending out a simple SMS message, but the basic steps can all be expanded on for more complex scenarios once the foundation is properly laid.

What You’ll Need Before You Start

Before writing code, make sure you have:

• A RingCentral developer account, obtained here: https://developers.ringcentral.com
• An app created in the RingCentral Developer Portal
• Your Client ID, Client Secret, and Server URL
• A RingCentral phone number enabled for SMS

Once you have those, you’re ready to connect your Python app to RingCentral.

Step 1: Install the RingCentral Python SDK

The RingCentral SDK handles authentication, HTTP requests, and error handling so you don’t have to build everything from scratch.

Install it using pip:

pip install ringcentral python-dotenv

This adds the SDK to your Python environment so your app can communicate with RingCentral’s REST API. We are also installing the environment settings package that allows us to store our app credentials in a secure location. You can create a separate file called .env and load it with the following information:

We will pick up these values later in our code sample. In a production environment you would “hide” this file in a sub-folder and place it in .gitignore to protect these keys from unauthorized use.

Step 2: Authenticate Your Application

RingCentral uses OAuth 2.0 for authentication. Your app must log in before making API calls so we use the dotenv approach to manage that information. Create a python code file called rc_app.py and start it with the following code:

import os, sys, time
from dotenv import load_dotenv
from ringcentral import SDK
load_dotenv()
CLIENTID = os.environ.get('RC_APP_CLIENT_ID')
CLIENTSECRET = os.environ.get('RC_APP_CLIENT_SECRET')
SERVERURL = os.environ.get('RC_SERVER_URL')
JWTKEY = os.environ.get('RC_JWT_KEY')
FROMNUMBER = os.environ.get('RC_MOBILE_SENDING_NUMBER')
ENDPOINT = os.environ.get('RC_ENDPOINT')

This loads the values that are stored in the .env file into our code and stores them in appropriately named variables. Next we want to create a connection to the RingCentral SDK using our credentials. Then we set up our specific parameters for the SMS message that we want to send and load that into the bodyParams array variable.

rcsdk = SDK(CLIENTID, CLIENTSECRET, SERVERURL)
platform = rcsdk.platform()
platform.login( jwt=JWTKEY)
# Set Params
bodyParams = {
 'from': {'phoneNumber': FROMNUMBER },
 'to': [ {'phoneNumber': '+19025551234' } ],
 'text': 'My first RingCentral Python SMS',
}

Lastly, all we have to do is send the end point value and the parameter array to the API with the post method. Optionally, we can send a little note to the display that the SMS was sent out successfully.

platform.post(ENDPOINT, bodyParams)
print("SMS sent successfully")

Our SMS message should look like the following.

Our on screen display should look like this.

For more robust coding you can put the post call within a try block and trap any errors that may be returned by the API. You can also store the response object from a successful post and display any of that supporting information as needed. The try block could look like this.

try:
 response = platform.post(ENDPOINT, bodyParams)
 jsonObj = response.json()
 print ("SMS sent successfully. The Message id is : " + str(jsonObj.id))
except Exception as e:
 print (e.message)

And the output on success would be

The output for an error would be a lot more involved and hopefully be helpful; pointing you to the cause of the error. It would look something like this.

You could clean this up substantially by storing the error code and message from the object into variables and sending those to the display. The code would look like the following and the displayed output follows that.

except Exception as e:
# RingCentral API errors land here
 error_data = e.api_response().json_dict()
error_code = error_data.get("errorCode", "Unknown")
 error_message = error_data.get("message", "No message returned")
print("An error occurred trying to send an SMS. ")
 print(f"Error Code: {error_code} Message: {error_message}")

Final Thoughts

Integrating RingCentral APIs into Python applications opens the door to powerful communication workflows; from SMS alerts and voice calls to reporting and automation. By using the official Python SDK and planning for authentication you can build systems that are not just functional, but production-ready.

Whether you’re sending customer notifications, internal alerts, or building analytics dashboards, these foundations will help your Python app communicate with confidence.

A Simple Guide to using the RingCentral API in Python Applications was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

If your team uses RingCentral for voice calls and a CRM (like Salesforce, HubSpot or Zoho) to manage customer records, capturing detailed call information in your CRM can be a real game-changer. Call analytics help you understand agent performance, track engagement, and automate workflows like follow-up calls or calculating billing.

There are two main ways to work with RingCentral’s call data.

Firstly, the Call Log section of the API gives you the raw call detail records with timestamps, direction (in bound or out bound), duration, result, and even recordings (if available). It’s ideal if you want to pull every completed call into your CRM’s activities.

Secondly, the Business Analytics portion of the API provides aggregated metrics, like daily call volumes or average handle time; useful for dashboards and performance reporting.

In this guide we will walk through:

• Authenticating with RingCentral in PHP
• Fetching call logs with the API
• Inserting those logs into your CRM
• Pulling analytics summaries for reporting

Everything is demonstrated with the official RingCentral PHP SDK.

Fetching Call Logs and Logging to CRM

What the Call Log API Provides

RingCentral’s call log endpoint returns completed calls with useful metadata like caller and callee phone numbers, call start / end timestamps, call duration and result (answered, voicemail, missed, etc.), and recording URLs if available.

The basic REST endpoint is:

$endpoint = "/restapi/v1.0/account/~/extension/~/call-log";

Here is a PHP snippet that pulls call logs for the past 15 days and then shows how you might iterate over them to send to a CRM. Depending on your call volume you may want to limit the time frame to each day (-1 day).

$endpoint = "/restapi/v1.0/account/~/extension/~/call-log";
$params = [
'dateFrom' => date('c', strtotime('-15 day')),
'dateTo' => date('c'),
];
$response = $platform->get($endpoint, $params);
$data = $response->json();
$records = count($data->records);
echo_spaces("call records count", $records, 2);
foreach ($data->records as $call) {
 echo_spaces("call session ID", $call->sessionId);
 echo_spaces("call direction", $call->direction);
 echo_spaces("call from", $call->from->name);
 echo_spaces("call from #", $call->from->phoneNumber);
 if (!empty($call->to->name)) {
 echo_spaces("call to", $call->to->name);
 } else {
 echo_spaces("no call to name");
 }
 echo_spaces("call to #", $call->to->phoneNumber);
 echo_spaces("call type", $call->type);
 echo_spaces("call Start time", $call->startTime);
 echo_spaces("call length", $call->duration);
 if (!empty($call->recording->contentUri)) {
 echo_spaces("call recording", $call->recording->contentUri);
 } else {
 echo_spaces("no recording");
 }
 echo_spaces("call result", $call->result, 1);
 //echo_spaces("call object", $call, 1);
}

This foreach loop extracts fields from each call log and displays them on the browser. This is for demonstration purposes, you might not do this if you were moving the data directly into your CRM. The above code would produce output like this:

You could then take those call values and connect to your CRM API, inserting them into that platform. The last line of the above code that is commented out would show you the whole call object if you wanted to collect some other information that I have not highlighted here. You can take that additional information into your CRM as well, if there is space for it. The full object structure looks like this:

Recording URLs

If a call has a recording (the call was recorded during the call as opposed to a voicemail), RingCentral’s call log includes a recording object so you can test to see if a recording of a particular call was made:

if (!empty($call->recording->contentUri)) {
 echo_spaces("call recording", $call->recording->contentUri);
} else {
 echo_spaces("the call was not recorded");
}

Your CRM records can then be linked to the audio file for playback by storing the URL.

Pulling Analytics with RingCentral Business Analytics API

If you want aggregated insights, not just individual call records, the Business Analytics API is the portion to use. This API gives you counts and durations broken down by timeframes like daily, weekly, or monthly. Typical analytics use cases include cumulative counts for daily inbound vs outbound calls, average handle time per user, and peak call hours.

Note: your RingCentral app that your code uses to authenticate will have to have “Analytics” as part of its scope. The Analytics endpoints use a POST body to specify the time range and grouping. Here is an example:

$endpoint = "/analytics/calls/v1/accounts/~/aggregation/fetch";
$analyticsBody = [
'grouping' => [
'groupBy' => 'Users',
],
'timeSettings' => [
'timeZone' => 'America/Los_Angeles',
'timeRange' => [
'timeFrom' => '2025–09–01T06:07:00.000Z',
'timeTo' => '2026–02–02T08:20:00.000Z',
],
],
'responseOptions' => [
'counters' => [
'allCalls' => [
'aggregationType' => 'Average',
'aggregationInterval' => 'Month',
],
'callsByDirection' => [
'aggregationType' => 'Max',
'aggregationInterval' => 'Week',
],
'callsByOrigin' => [
'aggregationType' => 'Sum',
],
'callsByResponse' => [
'aggregationType' => 'Min',
'aggregationInterval' => 'Day',
],
'callsSegments' => [
'aggregationType' => 'Average',
'aggregationInterval' => 'Hour',
],
'callsByResult' => [
'aggregationType' => 'Min',
'aggregationInterval' => 'Month',
],
'callsByCompanyHours' => [
'aggregationType' => 'Min',
'aggregationInterval' => 'Hour',
],
'callsByActions' => [
'aggregationType' => 'Min',
'aggregationInterval' => 'Hour',
],
'callsByType' => [
'aggregationType' => 'Min',
'aggregationInterval' => 'Hour',
],
],
]
];
try {
$response = $platform->post($endpoint, $analyticsBody);
$analyticsData = $response->json();
$records = count($analyticsData->data->records);
echo_spaces("call records count", $records, 1);
foreach ($analyticsData->data->records as $record) {
// echo_spaces("Record name", $record->info->name);
if ($record->info->name == "Peter MacIntyre") {
echo_spaces("Record details for ", $record->info->name, 1);
// echo_spaces("Record object for Peter MacIntyre", $record);
echo_spaces("Extension Number", $record->info->extensionNumber);
echo_spaces("Number of inbound calls", $record->counters->callsByDirection->values->inbound);
echo_spaces("Number of outbound calls", $record->counters->callsByDirection->values->outbound);
}
}
} catch (\RingCentral\SDK\Http\ApiException $e) {
echo_spaces("Error code", $e->getCode());
echo_spaces("Error message", $e->getMessage());
// echo_spaces("Error Object", $e);
throw $e;
}

This code produces the following object output, ahead of the objects, I send out a total count to the browser of all the records so that I can gauge my overall volume.

You can then fine tune the provided information and select the specific information that you are interested in. Here I am sending out specific data of the count of the inbound calls and the outbound calls for a selected caller, me.

You can also manipulate the resulting summary data by adjusting the responseOptions values. To see all the combinations available, check out the documentation here and here. This can all provide a dataset of aggregated metrics you can present in dashboards or store in CRM custom. objects.

Closing Thoughts

Integrating RingCentral’s call data into your CRM unlocks better visibility into your team’s communication activities. The Call Log API gives you detailed records you can map directly to CRM activities, while the Business Analytics API helps you generate custom dashboards and insight reports automatically.

Once you have authenticated your PHP backend with the RingCentral SDK, you can retrieve, transform, and push call events into your CRM’s activity history with relatively few lines of code, making your CRM the single source for customer interactions and performance analytics.

How to Use RingCentral APIs to Log Call Analytics in Your CRM was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

RingCentral’s Workflow Builder is nearing GA (General Availability). This is exciting news as it will imbue RingCentral voice, SMS, video, and team messaging with automated processes that you can create without any programming knowledge.

In this tutorial, I’ll show you how you can test and debug your workflows.

To get started, after you log into the RingCentral desktop application, or its equivalent website interface, you should see “Workflows” on the left panel. If it is not there, look under “More” also on the left panel. You can drag and drop the icon to the main left panel if you would rather not have to access it under the “More” option.

When clicked you will be taken to the dashboard area that lists all your existing workflows, if any.

It should look similar to the following image.

In our example [1], we are wanting to test the “SMS Product Support Request” workflow. This workflow was built to respond to a received SMS message if it contained the text of “support request” and then if it contained the text of “SMS granted”. It is shown in the figure below. In the first condition [1], if the incoming SMS text contains the words “support request” or “help”, we want to post a note to a Team Messenger chat group [2] with the full text of the received SMS.

Hopefully, the incoming text will be descriptive and concise enough that the support team can lend assistance. In our workflow the group receiving the note about a new support request is called “Messenger Tests”, but this can be updated to any individual or group chat that the account has access to. The next condition [3] is another query on the incoming text to see if the string “SMS granted” is also contained within it. If the case is true [4], then we send a courteous SMS message back to the sender telling them that the message was received and that it would be worked on as soon as possible. We take no action on the false conditions of either case.

Testing a workflow

Once you have your workflow designed to a point where you want to test it, you can save it and then test it by clicking the “Simulate” button at the top right of the design area. The “Simulate” pop-up screen will display and you can enter in any sample information that the workflow needs. In our case we need to provide a sender’s mobile number [1], the sender’s name [2], and the body of the text message [3] that we want to send. We can change the sender’s name if we like, but “John Doe” is fine for testing purposes. The test screen should look like the following.

If you look at the logical flow of the workflow you will see that based on the content of the message text. This should do nothing and fall down through the initial “false” side of the process. Here is the result screen of the test:

The areas of the workflow that were tested are listed with what they were testing for (our search conditions) and what they were testing against (the incoming SMS message). Then the results of each of the tests are shown (pass: true/false). We can click “Simulate again” to perform more tests on different scenarios. As we perform other tests on different text message content, we can see the simulated results each time.

Following are the results of another test SMS that contains only the text “Help SMS granted”. This is the content that we are testing for in each branch so both conditions should prove to be true and we should get a message sent to the chat group as well as a response message to the sender.

If any of the process steps fail, for example a bad phone number was used, then the error will be identified as accurately as possible by the simulation environment.

All of the above tests have been performed on the workflow while it was being built or edited in the workflow design area. After you complete your workflow and “Enable” it, there is another way to see the results of its activities. RingCentral Workflow Builder keeps a results log of your workflow when it runs. You can view your logs on the dashboard screen by clicking on the history link. The following image shows this for you.

You should then see a log of activity that your workflows have generated so far. Here is a screen shot of that history page. If there were errors, you should see them listed in the status column.

If you click on the status word of “Successful” or “Failed” you will see the details of the workflow when it last ran. An example of the “failed” log look like this:

RingCentral Workflow Builder is a great time saver when your workflows perform as desired. Workflows can grow to be quite complex and sometimes hard to follow so it is a good idea to test your workflows thoroughly before they are enabled. Be sure to also occasionally check the log page to ensure that your workflow is running at its best.

To learn more about RingCentral Workflow Builder, and see samples of other workflows you can build, visit our Workflow Builder Developer page.

Test and Debug workflows in Workflow Builder was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

There are often times when you are using the RingCentral API within your applications that you would like to know when an event has occurred, such as receiving a voicemail, SMS, FAX, or page. As these events never occur on a set schedule, the RingCentral platform has to make your applications aware of the event so you can act on it. The event notifications aspect of the API is where you want to start. In this article, I will show you how to make use of this API endpoint and how you can leverage it to provide the information that you want from these types of events. This can help with keeping track of response times in the case of customer support, for example.

I have created a small app that you can use as a starting point and the code is located here. In this app, I created webhooks that listen for these types of events and can be programmed to react in a desired fashion like sending out a Team Messaging notification or an SMS message. Let’s get started by looking at what a webhook is and why we need them in this case.

Webhooks

A webhook, also known as a subscription, is a notification request event that you can place on the RingCentral API server requesting that it notify you when specified events occur. For example, when someone sends you a fax message you can tell the RingCentral API server to watch for these incoming types of communication and let you know about it. There are a few rules about how you can create a webhook in terms of what it needs to be able to send you the event notifications and they are:

1. You need to have a code file on your own server that it can communicate with.
2. Your code file cannot be behind a firewall.
3. The web server that your own code sits on must support TLS 1.2 or higher.
4. Your own web server must be able to respond within 3000 milliseconds.
5. The web server must respond with an HTTP 200 OK code.
6. The web server must respond with a valid validation token header.
7. The web server must not respond with anything larger than 1024 bytes.

When you send a request to the API to create a webhook the target file has to exist as a minimum, then all the other items on the above list will need to be in place before the webhook can start to send you any notifications. Let’s look at the code to get a better idea of how this is all accomplished.

$api_call = $controller['platform']->post('/subscription',
 array(
 "eventFilters" => $event_filters,
 "expiresIn" => "315360000",
 "deliveryMode" => array(
 "transportType" => "WebHook",
 // need full URL for this to work as well
 "address" => $subscription_url, )
 )
 );

Here is the basic creation statement that we send to the RingCentral API with a post method call. The endpoint is “/subscription” and the parameters are sent within an array structure.

The “eventFilters” are the items that you want to be notified about. More on that later. The “expiresIn” option can be left as a default of seven days but can be set as high as the number shown above which equates to almost 10 years. The number is in seconds.

The “deliveryMode” is also in an array structure and we send over the type of subscription we are creating, “WebHook”, and the “address” which is the URL of our code file that the webhook will be running if and when an event occurs. I am using a few variables here and we will explore those next.

eventFilters

The “eventFilters” value that is being sent to the subscription post method is an array of all the events that you want this webhook to react to. In our code, we test to see if a webhook of the requested type already exists and we therefore don’t create one if the case is true. If we do need to create a webhook for the designated event type then we have to add that request to the $event_filters array. The code for creation of an incoming SMS notice will look like this and naturally precedes the code above.

$event_filters[] = "/restapi/v1.0/account/~/extension/~/message-store?type=SMS&direction=Inbound";

So we have to set the type and the direction of the filter as query string options on the message-store endpoint. There are a total of 8 endpoints of this nature that you can be notified about. They are SMS, Voicemail, Fax, and Pager; each has an inbound and outbound value. In our app we only want to be notified of incoming (inbound) events.

Subscription URL

The other variable that I am using is the code file that I want the webhook to call when an event actually occurs. I set this value in my .env environment file and call it into existence earlier in the code. The url value in my case is:

RC_WEBHOOK_URL_SUFFIX = '/real_time_events/process_webhooks.php'

And I concatenate this with the full url path to my application host with this line of code:

$subscription_url = "https://" . $_SERVER['HTTP_HOST'] . $_ENV['RC_WEBHOOK_URL_SUFFIX'];

So my file called process_webhooks.php has to exist on my server, in the folder specified, not behind a firewall, etc. in order to have the webhook created when I call this API endpoint.

The application interface

Our application’s home page looks like this:

Here we can request the creation of the webhook notification events with the checkboxes and also list any existing webhooks should we forget which ones we already have active. If I ask for the creation of a Voicemail and SMS webhook and one already exists for Voicemail, I will see this on the screen.

This is all done within the create_webhook.php code file after I place the values of the checkboxes into the $_SESSION, so be sure to explore that for full coverage of the creation of a webhook.

Show Existing Webhooks

The other link I have on my home screen is a call to list_kill_webhooks.php. This is a code file that checks to see if there are any existing webhooks and then displays them to the browser. I also have a few lines of code in this file that by all rights should be in its own code but I have it there for convenience. It is code that will delete an existing webhook by providing the subscription Id.

The bulk of the code file is as follows:

$controller = ringcentral_sdk();
// list subscriptions then optionally delete the one we don't want.
try {
 $response = $controller['platform']->get("/subscription");
 $subscriptions = $response->json()->records;
} catch (Exception $e) {
 echo_spaces("catch error", $e->getMessage());
}
foreach ($subscriptions as $subscription) {
// echo_spaces("Subscription Info", $subscription, 2);
echo_spaces("Subscription ID", $subscription->id);
 echo_spaces("Creation Time", $subscription->creationTime);
 echo_spaces("Expires", $subscription->expirationTime);
 echo_spaces("Webhook URI", $subscription->deliveryMode->address);
 echo_spaces("Webhook transport type",
 $subscription->deliveryMode->transportType);
 foreach ($subscription->eventFilters as $event_url) {
 $query = parse_url($event_url, PHP_URL_QUERY);
 parse_str($query, $params);
 echo_spaces("Event Type", $params['type']);
 }
 echo_spaces("Event Filter(s) URI", $subscription->eventFilters);
if ($subscription->id == "f7a15b17–3339-xxxxxxx-b2e8e96d28a3") {
 $response = $controller['platform']->delete
 ("/restapi/v1.0/subscription/$subscription->id");
 echo_spaces("Subscription ID Deleted", $subscription->id, 1);
 }
}

First we connect to the SDK receiving a $controller handle. Then with the SDK connection we call the get method to the subscription endpoint to be given all the currently active subscriptions. This information is stored in the records array and we place it in our local variable called $subscriptions. Then we traverse that array listing the information that is available for each existing webhook. We show the id, creationTime, expirationTime, and so on. The commented line above will list all the elements of the array if you ever want to see all the information that is available in that array and maybe want to display additional webhook information.

Within that array is another array of the eventFilters (individual events) that are part of the individual webhook. So for example, we could have one webhook that is watching for both Voicemail and SMS inbound events. I tease out the event type from the provided URL of the event then show the full event URL for confirmation.

Lastly, I check on an individual subscription id to see if it is provided to my code and then I delete it. This is a manual process that I need to update my code file each time and then re-run it in order for the delete process to actually be accomplished. I only provide it here as an example of how a subscription can be removed.

The output of the above code, without a deletion request would look like this.

Processing the event(s)

The last piece of this puzzle is what you want your code to do when the created webhook(s) actually record an event and notify you. We have the code file already designated when we created the webhook. In our case it is called process_webhooks.php.

Let’s look at the code in sections. The first significant step is this.

$hvt = isset($_SERVER['HTTP_VALIDATION_TOKEN']) ? $_SERVER['HTTP_VALIDATION_TOKEN'] : '';
if (strlen($hvt) > 0) {
 header("Validation-Token: {$hvt}");
}
$incoming = file_get_contents("php://input");
// use following to send incoming event data to a file for visual review
file_put_contents("received_EVENT_payload.log", $incoming);

Here we prepare the validation token to be matched with the token that is coming from the event notification that RingCentral is providing. Once matched we can continue with the code. We take the incoming data and store it into a variable called $incoming and then optionally we store it on our server with the file name of received_EVENT_payload.log. A sample of the incoming data would look like this.

{"uuid":"5710691562723757251","event":"/restapi/v1.0/account/5499917/extension
/62177786016/message-store","timestamp":"2025–08–28T18:20:28.565Z",
"subscriptionId":"2b95d0da-xxx-4fb6–82c3–38d26fa5c498","ownerId":
"621555486016","body":{"accountId":5414445017,"extensionId":621555486016,
"lastUpdated":"2025–08–28T18:20:18.543Z","changes":[{"type":"SMS",
"newCount":1,"updatedCount":0,"newMessageIds":[3099897302017]}]}}

The important part of this data is what comes after the “changes” designation. Here we see that the event is an SMS message and we are provided with the message id as well if we want to do anything further with it.

Back to the code, after a few data integrity checks we see this.

// get the type of event
$incoming_event_type = 
 htmlentities($incoming_data->body->changes[0]->type);
// handle the type of the event with notifications or SMS or whatever you want.
echo_spaces("Event Type", $incoming_event_type, 1);
echo_spaces("Event Info", $incoming_data->body->changes, 1);

I draw out the type of the event from the changes[0]->type section and then simply show the information on the browser.

I use the postman site to test this code. It’s a great way to play with the outcome of your notification code that is usually non-visual. The echo statements can be seen in the postman “preview” area when you send the “Body” to the specified URL. It essentially mimics a notification call that the webhook would be doing. Here you can see the output of a new fax notification showing the event type and the event info as displayed by the echo statements.

To make it truly a notification you could use the API to send yourself an SMS when a new fax or voicemail came in, or send some information to a Team Messenger group. There are a lot of options to consider here, but the point is that you can react to almost any event that you want with this API. You can even take some notifications from the audit trail system and handle them in a similar way. All you have to do is specify the event type when creating a webhook and have access permission to the audit trail system (which is usually at least admin level access).

Developer App Setup

The only thing left to make note of is how to set up the developer app so that you would have the correct access to the message-store and subscription endpoints. The app scope for the message store is called “Read Messages” and the scope for webhooks is “Webhook Subscriptions”.

Additionally, if you wanted to send out SMS, or Team Messaging notifications when events occur you would have to add “SMS” and “Team Messaging” to the scope of your application. Don’t forget to add the client id, client secret, and JWT codes to your .env file when you have those created as part of your application development environment.

That is all there is to getting event notifications and handling them when they occur. I hope you can make use of these code examples and maybe leverage it to make your own applications more robust when interacting with the RingCentral API.

Real-time Event Notifications with RingCentral’s API was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

As you might be aware every RingCentral account includes multiple contact lists, but did you know that they can all be accessed within an API? Through the API, contact lists can be shared with other applications or downloaded for processing. Although there are several categories of contacts that you can see on the Contacts tab within the RingCentral app, we will focus on the two most used categories: Company and Personal.

The first group of contacts that we will be looking at is a collection of Company contacts or internal contacts. These are contacts that are input from your company’s LDAP or directory server. The API provides read-only company contacts and cannot add new contacts to it. The second group of contacts that you have access to are personal contacts. This is a list of contacts that you can control. This is a little different than a list of personal contacts that is accessed through your Google or Apple accounts. These are contacts that you enter yourself into the RingCentral platform.

If you are using Team Messenger you should be able to see these contact lists in the Contacts section.

In this article, I will show you how to access these lists and some of the things that you can do with the returned information. I have created a small app in PHP that I will use for these demonstrations. Be sure to add “ReadAccounts” and “ReadContacts” as app scopes to your RingCentral Developers app if you are following along with the code. The “ReadAccounts” scope will be used for retrieving the Company contact information and “ReadContacts” will be used to access the personal contact information. The code base can be found on GitHub here.

Company Contacts API

We will start with the company contacts listing. As mentioned above, we can only retrieve the information through the API and not add any new records. Our landing page then only offers a submit button to bring out that data. The home page looks like this.

Here, we only want to click the “Retrieve Company Contacts” button, the other form parts are for the Guest Contacts, so ignore those for now.

I wrote the code for bringing in the Company contacts and encased it within a function that is called when the button is clicked. It looks like the following.

function get_company_contacts() {
 $controller = ringcentral_sdk();
 $platform = $controller['platform'];
$endpoint = "/restapi/v1.0/account/~/directory/entries";
try {
 $resp = $platform->get($endpoint);
 $records = $resp->json()->records; // array of objects
if (count($records) >= 1) {
// usort($records, function ($a, $b) {
// $lastA = $a->lastName ?? '';
// $lastB = $b->lastName ?? '';
// return strcmp($lastA, $lastB);
// });
 foreach ($records as $record) {
 // echo_spaces("Response record", $record);
 if ($record->status == 'Enabled') {
 echo_spaces("Contact ID", $record->id);
 echo_spaces("Contact Status", $record->status);
 echo_spaces("Contact name", $record->firstName . ' ' .
 $record->lastName);
 if (!$record->jobTitle) {
 echo_spaces("No Job Title listed");
 } else {
 echo_spaces("Contact Job Title",$record->jobTitle);
 }
 echo_spaces("Contact account id",$record->account->id);
 echo_spaces("Contact extension #",
 $record->extensionNumber);
 if ($record->profileImage) {
 $img_account = $record->account->id;
 $img_extension = $record->id;
 $img_endpoint =
"/restapi/v1.0/account/$img_account/extension/$img_extension/profile-image/90x90";
// $img_endpoint = "/restapi/v1.0/account/$img_account/extension/$img_extension/profile-image/195x195";
 $img_resp = $platform->get($img_endpoint);
 $contentType = 
 $img_resp->response()->
 getHeaderLine("Content-Type");
 $binary = $img_resp->raw();
 $base64 = base64_encode($binary);
 $imageSrc = "data:$contentType;base64,$base64"; ?>
<img src="<?php echo $imageSrc; ?>" alt="Profile">
 <br/>
 <?php } else {
 echo_spaces("Contact profile image not found.", "", 2);
 }
 }
 }
 } else {
 echo_spaces("No contact records found for provided
 parameters.");
 }
 } catch (\RingCentral\SDK\Http\ApiException $e) {
 // craft a friendly error message here.
 echo_spaces("There was an error retrieving the contacts list,
 Please try again later", $e->getMessage());
 }
}

The endpoint for this API call is: /restapi/v1.0/account/~/directory/entries

After we get our connection to the API with the sdk() call, we call the get method on the platform object passing in this endpoint. We are then given the response object with all the company contact information that is related to the specified account.

After checking that there is at least one record returned, there is a block of code that is commented out that can help to sort the object elements by “lastName”. You can uncomment this out and adjust it if you need to sort the retrieved information. Next we step through all the records and see if they are “enabled” before we do anything with them. If they are enabled, then we start to send out the information to the browser in a human-readable format.

Each company contact also has the potential to have a profile image associated with it. So we are using another aspect of the API to bring back a profile image if one exists. You will see a variable called $img_endpoint that calls another get method with the provided account and extension numbers added and the dimension of the image at the end — 90x90. There is also a 195x195 dimension option that I have added as a comment if you want to see what the larger images may look like. After the new endpoint is called we process the image information and craft an HTML image output line within the overall loop, so that we can see an image for each company contact. When we run this code we should see output like this.

Personal Contacts API

The API endpoint for the personal contacts is different from the Company one. This is partially due to the fact that you can control the content of these contacts. The endpoint for personal data is: /restapi/v1.0/account/~/extension/~/address-book/contact

Here we see that the main difference is /address-book/contact

The criterion for the endpoint also allows for a few parameters. The first one is “startsWith”; this allows you to filter the returned records with only data that has a firstname or lastname that starts with a provided string. The second parameter is “sortBy” and this allows you to have the returned information sorted by first name, last name, or company data elements. We will see this in action shortly when we look at the code. The request form that I built is the same one from before but this time we have the option of passing in one or both of these optional parameters. Here, again, is the screen.

If we leave the “starts with” option blank and request that we sort the returned data by lastname the output will look like this:

The code for this is collected within a function called “get_guest_contacts” and we pass over the 2 parameters for the endpoint as options within the structure of the function. Here is the code for the function:

function get_guest_contacts($startsWith = "", $sortBy = "") {
$controller = ringcentral_sdk();
$platform = $controller['platform'];
$queryParams = array(
'startsWith' => $startsWith,
'sortBy' => $sortBy,
);
$endpoint = "/restapi/v1.0/account/~/extension/~/address-book/contact";
try {
$resp = $platform->get($endpoint, $queryParams);
$records = $resp->json()->records; // array of objects
if (count($records) >= 1) {
foreach ($records as $record) {
echo_spaces("Contact ID", $record->id);
echo_spaces("Company", $record->company);
echo_spaces("Contact Last name", $record->lastName);
echo_spaces("Contact Full name", $record->firstName . ' ' . $record->lastName);
echo_spaces("Contact Home Phone #", $record->homePhone);
if (!$record->birthday) {
echo_spaces("No birthday listed");
} else {
echo_spaces("Contact Birthday", $record->birthday);
}
if (!$record->jobTitle) {
echo_spaces("No Job Title listed");
} else {
echo_spaces("Contact Job Title", $record->jobTitle);
}
if (!$record->notes) {
echo_spaces("No notes recorded", "", 2);
} else {
echo_spaces("Contact notes", $record->notes, 2);
}
}
} else {
echo_spaces("No contact records found for provided parameters.");
}
} catch (\RingCentral\SDK\Http\ApiException $e) {
// craft a friendly error message here.
echo_spaces("There was an error retrieving the contacts list, Please try again later", $e->getMessage());
// echo_spaces("details", $e);
}
}

The structure of this function is very close to the one that we used for company data. One of the main differences is that there is no associated image available for these contacts, so that has been removed from this code. Also, the ability to sort the information on a few criteria is available here and not with the company information.

One other thing that you can do with this endpoint, using the post method instead, is to create personal contacts. There are more queryParameters that are available when adding in a new contact, as one would expect and they can be found here. If you are considering using this process, you will have to add the “Contacts” scope to your developer app.

Further Reference

With this collection of information available to you via the API, there are quite a few things you can do with it. You can export the data to external systems, archive the data, or use individual record information to place personalized calls, SMS messages, or electronic fax transmissions. For more complete information on these API actions check out these links.

1. Address book developer guide: https://developers.ringcentral.com/guide/address-book
2. Address book API Reference — List User Contacts: https://developers.ringcentral.com/api-reference/External-Contacts/listContacts
3. Address book API Reference — Create User Contacts:
   https://developers.ringcentral.com/api-reference/External-Contacts/createContact
4. Address book API Reference — Get Company Directory Entries:
   https://developers.ringcentral.com/api-reference/Internal-Contacts/listDirectoryEntries

I hope you found this article useful and that you can see the potential of what can be done with this portion of the RingCentral API beyond what was demonstrated here.

Accessing Contact Information with RingCentral’s API was originally published in RingCentral Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.