Overview
Picture a CRM, field delivery platform, or order management system that works alongside Hipcall. The businesses using that software do not want to switch to the Hipcall dashboard every time they place a call, check who is calling while the phone rings, record that a call has ended, connect a courier through an order code, or attach a voice AI assistant to their phone line. They expect all of those actions to happen from the screen they already have open.
This series is for partners who build that kind of software. The business selects "Connect Hipcall" once in the partner's app and approves access. From then on, the app changes settings and sends API requests to Hipcall on the business's behalf.
This article explains how the flow works and introduces the six integration scenarios covered in the series. Set-up steps and runnable ASP.NET Core code samples are in each scenario's own article.
How the flow works
Everything starts with OAuth2. When the business selects the button in your app, it lands on Hipcall's sign-in and consent screen, sees which permissions (scopes) the app is asking for, and approves them. Hipcall then gives the app an access_token, which the app uses from that point on to place calls, create webhooks, open speed dial extensions, provision SIP connections, or push caller context cards to the agent's screen.
Nobody copies an API key from the dashboard, and the partner never sees the business's Hipcall password.
flowchart LR
A["Business selects Connect Hipcall"] --> B["Approves access on Hipcall"]
B --> C["App receives access_token"]
C --> D["Places calls with click-to-call"]
C --> E["Creates a webhook"]
C --> F["Opens a speed dial extension"]
C --> G["Provisions a Vapi SIP connection"]
C --> H["Shows caller context with Insight Card"]
The building blocks
OAuth2
OAuth2 is the authorisation standard that lets an app access another service on a user's behalf. With Hipcall, the app sends the user to /oauth/authorize. Once the user approves, the app exchanges the returned one-time code for an access_token at /oauth/token:
POST https://use.hipcall.com/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=https://your-app.com/callback
The token lasts about an hour. If the app asks for the offline_access scope, the response also includes a refresh_token. Scopes decide what the app can reach; creating a webhook needs webhooks:write, while managing speed dial and SIP connections needs communication_settings:write.
If you want to add a "Connect Hipcall" button to your app and run your first token exchange, start with How to Authorise Users and Get Tokens with Hipcall OAuth2.
Click-to-call
Click-to-call starts an outbound call from a button inside your app. When an agent selects "Call" on a customer record in the CRM, the app sends a request to POST /api/v3/users/{user_id}/call:
{
"callee_number": "+447700XXXXXX",
"ring_user_first": true,
"number_id": 942,
"call_masking": true,
"call_masking_name": "Support Team"
}
With ring_user_first: true, the agent's Hipcall app rings first and the customer is dialled once the agent answers. Setting call_masking: true hides the customer's phone number from the agent and displays call_masking_name on the screen instead. The customer sees the company number (number_id) rather than the agent's personal one.
If you want to start outbound calls from a button in your own interface and mask customer numbers, see How to Start Click-to-Call Outbound Calls with OAuth2.
Webhooks
A webhook is a signed HTTP POST request that Hipcall sends to your server when something happens in the account. When a call ends, Hipcall posts a call.ended event to your HTTPS address. Your app can create the webhook subscription itself through POST /api/v3/webhooks using its OAuth2 token:
{
"url": "https://your-app.com/hipcall/events",
"description": "Acme SaaS call.ended integration",
"events": ["call.ended"],
"send_record_links": false
}
Because the app registers the webhook through the API, the business does not have to open the dashboard or copy the whsec_ signing secret across by hand. Your server verifies the webhook-signature header with HMAC-SHA256 on every request before recording the call duration and hangup details.
If you want to subscribe to call events automatically and verify incoming signatures, read How to Set Up Webhooks Through the OAuth2 API.
Speed dial
Speed dial is an internal extension where your web service decides which number gets called. It suits field delivery and courier operations where data protection rules such as GDPR mean the courier should not hold the customer's personal phone number. Using its OAuth2 token, your app calls POST /api/v3/speed-dials to create a speed dial extension such as 7001 on the business's account.
When a courier dials extension 7001 and keys in order number 1234, Hipcall sends those digits to your web service in a POST request:
{
"timestamp": 1791891730,
"number": "1234",
"uuid": "e7850000-0000-4000-8000-0000000087e5",
"user_id": 4200,
"speed_dial_id": 19
}
Your service looks up the order, replies with { "destination": "447700XXXXXX" }, and Hipcall dials the customer. The courier talks to the customer without ever seeing their phone number.
SIP connections and Vapi
SIP is the protocol used to set up voice calls over the internet. An external SIP connection links a phone number and extension on Hipcall to another SIP system. That system could be an IP PBX in the office, or a voice AI platform such as Vapi that answers incoming calls.
In a Vapi integration, incoming calls are answered first by the AI voice assistant; when the caller asks to speak to a person, Vapi uses its Transfer Call tool to transfer the call over SIP back to a Hipcall extension (such as extension 20). With an OAuth2 token, your app can look up the active number (GET /api/v3/numbers), find an unused extension (GET /api/v3/extensions), and create the Vapi SIP connection in one click via POST /api/v3/sip-connections:
{
"name": "vapi-assistant",
"extension_number": 4001,
"number_id": 942,
"termination_uri": "sip:sip.vapi.ai",
"username": "vapi_hipcall_4001",
"termination_auth_enabled": true,
"termination_auth_username": "+442079XXXXXX",
"termination_auth_password": "YourStrongChosenPassword123!"
}
Calls to extension 4001 or the linked phone number are then routed directly to the voice assistant at sip:sip.vapi.ai.
If you want to route incoming calls to a Vapi voice assistant and transfer callers to a live agent when needed, read How to Set Up a Vapi SIP Connection Through the OAuth2 API.
Insight Card
Insight Card displays customer details from your CRM directly inside the Hipcall Web Phone as soon as an inbound or outbound call starts. Before answering the call, the agent sees the caller's name, company, account balance, or latest order on the screen and can open the customer record in your CRM with one click.
When a call begins, Hipcall sends a call.initiated webhook event to your server. Your backend reads the call uuid and phone number from the event, looks up the customer in your CRM database, and sends the card payload to POST /api/v3/calls/{uuid}/cards:
{
"card": [
{
"type": "title",
"text": "Acme CRM",
"link": "https://crm.example.com/customers/1234"
},
{
"type": "shortText",
"label": "Customer Name",
"text": "Alex Smith",
"link": "https://crm.example.com/contact/1234"
},
{
"type": "shortText",
"label": "Latest Order",
"text": "#9558 - Dispatched"
}
]
}
If you want to display CRM customer context on the agent's screen while the phone is ringing, see For Partners: Hipcall Insight Card Integration Guide.
Before you start
For the articles in this series, you need:
- A Hipcall plan that includes the API and webhooks.
- An OAuth2 application with a client ID, a client secret, and a redirect URI.
- The right permissions and scopes (
profile,offline_access,communication:write,webhooks:write,communication_settings:write) on the Hipcall user who approves access. - A server that is reachable from the internet. Webhooks and speed dial both rely on Hipcall sending requests to you. Webhook addresses must use HTTPS. During development, a tunnel such as ngrok will do.
Next steps
- Request your OAuth2 credentials and run your first token exchange in How to Authorise Users and Get Tokens with Hipcall OAuth2.
- See the click-to-call request and number masking in How to Start Click-to-Call Outbound Calls with OAuth2.
- Build the webhook flow in ASP.NET Core with How to Set Up Webhooks Through the OAuth2 API.
- Connect a Vapi voice assistant over SIP in How to Set Up a Vapi SIP Connection Through the OAuth2 API.
- Show customer details on the agent's screen during a call in For Partners: Hipcall Insight Card Integration Guide.
- Browse every endpoint in the Hipcall API reference.
- Ask questions in the Hipcall Community.