AI Features

SIPSIM offers powerful AI features to help you get more value from your calls. This guide covers call transcription and AI-generated summaries.

Required Scopes

Feature	Read	Write
Transcription	calls.transcription.read	calls.transcription.write
Summary	calls.summary.read	calls.summary.write
Settings	settings.read	settings.write

Call Transcription

Convert call recordings to text with speaker identification.

Trigger Transcription

To create a transcription for a call:

cURL

curl -X POST "https://app.sipsim.com/api/v2/calls/12345/transcription" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
call_id = "12345"

response = requests.post(
    f"https://app.sipsim.com/api/v2/calls/{call_id}/transcription",
    headers={"Authorization": f"Bearer {access_token}"}
)

if response.status_code == 201:
    print("Transcription started!")
else:
    print(f"Error: {response.json()['errors']}")

Processing Time

Transcription is processed asynchronously. For a 5-minute call, expect 30-60 seconds of processing time.

Get Transcription

Retrieve the transcription once it's ready:

cURL

curl "https://app.sipsim.com/api/v2/calls/12345/transcription" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests
import time

access_token = "YOUR_ACCESS_TOKEN"
call_id = "12345"

def get_transcription_with_polling(call_id, max_wait=120):
    """Get transcription, polling until ready."""
    start_time = time.time()
    
    while time.time() - start_time < max_wait:
        response = requests.get(
            f"https://app.sipsim.com/api/v2/calls/{call_id}/transcription",
            headers={"Authorization": f"Bearer {access_token}"}
        )
        
        if response.status_code == 200:
            transcription = response.json()["data"]
            if transcription.get("speech_state") == "speech_recognized":
                return transcription
            print("Transcription still processing...")
        
        time.sleep(5)  # Wait 5 seconds before polling again
    
    raise TimeoutError("Transcription not ready within timeout")

transcription = get_transcription_with_polling("12345")
for segment in transcription["payload"]:
    print(f"[Channel {segment['channel']}] {segment['text']}")

Transcription Response

{
  "status": 200,
  "request_id": "...",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "speech_state": "speech_recognized",
    "payload": [
      {
        "channel": 0,
        "start": 0.0,
        "end": 5.2,
        "text": "Bonjour, société SIPSIM, comment puis-je vous aider ?"
      },
      {
        "channel": 1,
        "start": 5.5,
        "end": 12.1,
        "text": "Bonjour, j'appelle concernant ma commande numéro 12345."
      }
    ]
  }
}

Transcription Fields

Field	Type	Description
speech_state	string	State of transcription (see below)
payload	array	Array of transcription segments

Speech States

State	Description
speech_sent_to_recognition	Transcription is being processed
speech_recognized	Transcription completed successfully
speech_recognition_failed	Transcription failed
speech_stored	Transcription stored
speech_storing_failed	Storage failed

Payload Segment Fields

Field	Type	Description
channel	integer	Audio channel (0 = first party, 1 = second party)
start	float	Start time in seconds
end	float	End time in seconds
text	string	Transcribed text for this segment

Call Summaries

Generate AI-powered summaries of your calls.

Generate a Summary

cURL

curl -X POST "https://app.sipsim.com/api/v2/calls/12345/summary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
call_id = "12345"

response = requests.post(
    f"https://app.sipsim.com/api/v2/calls/{call_id}/summary",
    headers={"Authorization": f"Bearer {access_token}"}
)

if response.status_code == 201:
    print("Summary generation started!")
elif response.status_code == 409:
    print("Summary already exists for this call")

Prerequisite

A call must have a transcription before you can generate a summary. If the call doesn't have a transcription, create one first.

Get Summary

cURL

curl "https://app.sipsim.com/api/v2/calls/12345/summary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
call_id = "12345"

response = requests.get(
    f"https://app.sipsim.com/api/v2/calls/{call_id}/summary",
    headers={"Authorization": f"Bearer {access_token}"}
)

if response.status_code == 200:
    summary = response.json()["data"]
    print(f"Summary: {summary['summary']}")

Summary Response

{
  "status": 200,
  "request_id": "...",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "summary": "Customer called about order #12345. They reported a delivery delay and requested an update. The employee confirmed the order is scheduled for delivery tomorrow and offered a 10% discount for the inconvenience. Customer accepted and seemed satisfied.",
    "summary_state": "processed",
    "setting": {
      "base_instructions": "Focus on action items and customer sentiment"
    }
  }
}

Summary Fields

Field	Type	Description
summary	string	AI-generated summary text (null while processing)
summary_state	string	State: created, processed, failed
setting	object	Summary generation settings

Summary States

State	Description
created	Summary generation started
processed	Summary completed successfully
failed	Summary generation failed

Custom Summary Instructions

You can customize how summaries are generated for a specific call:

cURL

curl -X PATCH "https://app.sipsim.com/api/v2/calls/12345/summary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_instructions": "Focus on sales opportunities and customer objections. Include any pricing discussed."
  }'

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
call_id = "12345"

response = requests.patch(
    f"https://app.sipsim.com/api/v2/calls/{call_id}/summary",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    },
    json={
        "base_instructions": "Focus on sales opportunities and customer objections. Include any pricing discussed."
    }
)

# This triggers a regeneration with the new instructions
summary = response.json()["data"]

Account-Wide Summary Settings

Configure default summary instructions for all future summaries:

Get Current Settings

curl "https://app.sipsim.com/api/v2/settings/summary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Settings

cURL

curl -X PATCH "https://app.sipsim.com/api/v2/settings/summary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_instructions": "Always include: 1) Main topic discussed, 2) Customer sentiment, 3) Action items, 4) Follow-up required (yes/no)"
  }'

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"

response = requests.patch(
    "https://app.sipsim.com/api/v2/settings/summary",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    },
    json={
        "base_instructions": """Always include:
1) Main topic discussed
2) Customer sentiment
3) Action items
4) Follow-up required (yes/no)"""
    }
)

settings = response.json()["data"]
print("Settings updated!")

Complete Workflow Example

Process a call with transcription and summary:

import requests
import time

access_token = "YOUR_ACCESS_TOKEN"
base_url = "https://app.sipsim.com/api/v2"
headers = {"Authorization": f"Bearer {access_token}"}

def process_call_with_ai(call_id):
    """
    Complete workflow: transcribe a call and generate a summary.
    """
    # Step 1: Get call details
    call_response = requests.get(f"{base_url}/calls/{call_id}", headers=headers)
    call = call_response.json()["data"]
    
    print(f"Processing call: {call_id}")
    print(f"  Duration: {call['duration_sec']}s")
    
    # Step 2: Check/create transcription
    trans_response = requests.get(f"{base_url}/calls/{call_id}/transcription", headers=headers)
    
    if trans_response.status_code == 404:
        print("Creating transcription...")
        requests.post(f"{base_url}/calls/{call_id}/transcription", headers=headers)
        
        # Poll for completion
        for _ in range(30):  # Max 2.5 minutes
            time.sleep(5)
            response = requests.get(f"{base_url}/calls/{call_id}/transcription", headers=headers)
            if response.status_code == 200:
                data = response.json()["data"]
                if data.get("speech_state") == "speech_recognized":
                    print("Transcription complete!")
                    break
        else:
            raise TimeoutError("Transcription timeout")
    
    # Step 3: Check/create summary
    summary_response = requests.get(f"{base_url}/calls/{call_id}/summary", headers=headers)
    
    if summary_response.status_code == 404:
        print("Creating summary...")
        requests.post(f"{base_url}/calls/{call_id}/summary", headers=headers)
        
        # Poll for completion
        for _ in range(12):  # Max 1 minute
            time.sleep(5)
            response = requests.get(f"{base_url}/calls/{call_id}/summary", headers=headers)
            if response.status_code == 200:
                data = response.json()["data"]
                if data.get("summary_state") == "processed":
                    print("Summary complete!")
                    break
        else:
            raise TimeoutError("Summary timeout")
    
    # Step 4: Get final results
    transcription = requests.get(f"{base_url}/calls/{call_id}/transcription", headers=headers).json()["data"]
    summary = requests.get(f"{base_url}/calls/{call_id}/summary", headers=headers).json()["data"]
    
    return {
        "call": call,
        "transcription": transcription,
        "summary": summary
    }

# Process a call
result = process_call_with_ai(12345)
print("\n=== Summary ===")
print(result["summary"]["summary"])

Best Practices

1. Check before creating — GET the transcription/summary first; if 404, then create
2. Implement polling — AI features are async; poll with reasonable intervals
3. Handle timeouts gracefully — Long calls may take longer to process
4. Use webhooks for production — Instead of polling, consider webhooks for completion notifications
5. Customize instructions — Tailor summaries to your business needs

Next Steps

• Managing Tags — Organize calls with tags
• API Reference — Complete API documentation