Telephony and SIP

Connect incoming and outgoing phone calls to GPT-Live through a SIP trunk. Your provider exchanges call audio with OpenAI, while your backend handles session configuration, call controls, and business logic. SIP signaling uses TLS, and GPT-Live requires SRTP for call audio.

• Handle an inbound call: receive an incoming-call webhook, then accept or reject the call.
• Place an outbound call: create a session to dial a phone number through your provider. No incoming-call webhook or accept request is needed.

Use a sideband connection when your backend needs to receive session events or send commands. It attaches to the existing conversation while SIP carries the audio. Assign one handler to each action so that duplicate webhook deliveries or events observed on multiple connections don’t execute tools twice.

Handle an inbound call

Route incoming phone calls from your SIP provider to your OpenAI project. Your backend receives a webhook and decides whether to accept each call.

Receive the incoming call

Configure your project’s webhook endpoint for live.transport.incoming. Verify the webhook signature and deduplicate deliveries, then accept or reject the call.

The webhook identifies a SIP call with data.type: "sip" and provides data.session_id. Use that session ID unchanged for every Live call action. Treat data.sip_headers as untrusted caller metadata, not authorization.

Existing integrations may still receive the deprecated live.call.incoming event, which has no data.type. During migration, handle both names and retain the old subscription until legacy deliveries and retries have drained. The same pending call can also emit a Realtime webhook; assign one handler to the accept/reject decision rather than accepting through both APIs.

Accept or reject the call

Apply your application’s authorization and routing rules. To accept the call, send an authenticated POST /v1/live/sessions/{session_id}/accept request with a top-level session object:

123456789{
  "session": {
    "type": "live",
    "model": "gpt-live-1",
    "instructions": "You are answering an inbound support call.",
    "audio": { "output": { "voice": "marin" } },
    "delegation": { "type": "client" }
  }
}

Use Authorization: Bearer $OPENAI_API_KEY from your trusted backend for call-control requests. Choose the voice and delegation mode at acceptance. SIP negotiates the audio format, so omit audio.format. The example selects client delegation; your backend must handle delegated work. See Delegation and tools for client and Responses configurations.

A successful acceptance returns 200 OK with an empty body after session initialization. Handle HTTP errors before treating the call as accepted.

To reject the call, send POST /v1/live/sessions/{session_id}/reject with a SIP status, such as { "status_code": 486 } for busy. The status must be an integer from 300 through 699. The first accept or reject decision wins; a later competing decision returns decision_already_made.

Attach your backend

After acceptance, connect a sideband WebSocket at wss://api.openai.com/v1/live/sessions/{session_id}/attach. Use the accepted session ID and the same project authentication and connection headers. Do not send session.start again.

SIP carries the call audio. Use the sideband for transcripts, delegation, tools, commands, and reflected audio. Choose one owner for each side effect, even if multiple connections observe an event.

Once connected, use the active call controls to send keypad tones, transfer the call, or hang up.

Place an outbound call

Call a phone number through your SIP provider with Create session. Your provider handles the phone network connection while GPT-Live carries the conversation.

Configure your trunk

Use a trunk that supports TLS signaling and SDES-SRTP media. Enable SRTP in your provider’s settings before placing a call.

Supply the trunk configuration with each request:

The provider endpoint must use sips: for TLS signaling. Don’t include credentials, paths, URI headers, or other URI parameters in the URL. Local hostnames and literal private or local IP addresses are rejected. Keep your OpenAI API key and SIP credentials on your server.

Create the session

Send POST /v1/live/sessions with your session configuration and transport.type: "sip". Choose the voice and delegation mode when creating the session. Omit audio.format because SIP negotiates the audio format.

This example uses curl and jq. Set OPENAI_API_KEY, SIP_USERNAME, and SIP_PASSWORD in your server environment, and replace the example provider endpoint and phone numbers with your own values. The example selects client delegation; your backend must handle delegated work.

123456789101112131415161718192021222324252627jq -n \
  --arg username "$SIP_USERNAME" \
  --arg password "$SIP_PASSWORD" \
  '{
    "session": {
      "model": "gpt-live-1",
      "instructions": "Help the user schedule an appointment.",
      "audio": { "output": { "voice": "marin" } },
      "delegation": { "type": "client" }
    },
    "transport": {
      "type": "sip",
      "destination": "+14155550123",
      "trunk": {
        "provider_url": "sips:sip.example.com:5061",
        "auth": {
          "type": "digest",
          "username": $username,
          "password": $password
        },
        "caller_number": "+14155550100"
      }
    }
  }' | curl https://api.openai.com/v1/live/sessions \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-

The request returns 200 OK after the session initializes:

1234{
  "session": { "id": "live_123" },
  "transport": { "type": "sip" }
}

This response doesn’t mean the call has been answered. It contains no SDP or trunk credentials. Preserve session.id unchanged for the sideband connection and call controls. You don’t need an incoming-call webhook or an accept request for an outbound call.

Monitor and end the call

Attach your backend to wss://api.openai.com/v1/live/sessions/{session_id}/attach using your OpenAI API key. Don’t send session.start again. The sideband connection carries conversation events, delegated work, and call progress while SIP carries the audio.

Each call-progress event includes event_id and session_id. Attach immediately after creation: the sideband only replays events from the preceding 3 seconds, so a later attachment can miss earlier call progress. Replayed events retain their original event IDs. Deduplicate events by event_id.

Once connected, use the active call controls to send keypad tones, transfer the call, or hang up. Keep the sideband open for session.closed and final usage as described in Usage and graceful close.

Handle limits and errors

Ringing is limited to 3 minutes, and a connected call is limited to 2 hours. These limits aren’t configurable in the creation request.

Invalid session configuration is returned on the creation request. Transport setup failures can return 502, and initialization timeouts return 504. After creation succeeds, monitor transport.failed for asynchronous setup failures.

Manage an active call

These controls apply to both inbound and outbound SIP calls.

Send and receive keypad events

The sideband receives transport.dtmf.received when the caller presses a key. To send a DTMF tone to the SIP trunk, send a transport.dtmf.send client event over the sideband WebSocket. After the tone is successfully sent, the sideband receives transport.dtmf.sent.

If you supply an event_id, the notification includes it as client_event_id; failures return an error event with error.client_event_id.

Transfer or end the call

To transfer the call, send POST /v1/live/sessions/{session_id}/refer with { "target_uri": "sip:agent@example.com" } for your destination. To hang up, send POST /v1/live/sessions/{session_id}/hangup with no request body. Both return 200 OK with an empty body on success.

Keep the sideband open until session.closed supplies final usage. See Usage and graceful close for usage reporting and close reasons.

Next steps with GPT-Live

• Webhooks and server-side controls: manage a session from your backend.
• Delegation and tools: connect speech to your reasoning and tool backend.
• Managing sessions: handle transcripts, session state, and close.

SIP is a protocol used to make phone calls over the internet. With SIP and the Realtime API you can direct incoming phone calls to the API.

Overview

If you want to connect a phone number to the Realtime API, use a SIP trunking provider (e.g., Twilio). This is a service that converts your phone call to IP traffic. After you purchase a phone number from your SIP trunking provider, follow the instructions below.

Start by creating a webhook for incoming calls, through your platform.openai.com settings > Project > Webhooks. Then, point your SIP trunk at the OpenAI SIP endpoint, using the project ID for which you configured the webhook, e.g., sip:$PROJECT_ID@sip.api.openai.com;transport=tls. For European data residency, use sip:$PROJECT_ID@sip-eu.api.openai.com;transport=tls instead. To find your $PROJECT_ID, visit settings > Project > General. That page will display the project ID, which will have a proj_ prefix.

When OpenAI receives SIP traffic associated with your project, your webhook will be fired. The event fired will be a realtime.call.incoming event, like the example below:

POST https://my_website.com/webhook_endpoint
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52 # unique id for idempotency
webhook-timestamp: 1750287078 # timestamp of delivery attempt
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= # signature to verify authenticity from OpenAI

{
  "object": "event",
  "id": "evt_685343a1381c819085d44c354e1b330e",
  "type": "realtime.call.incoming",
  "created_at": 1750287018, // Unix timestamp
  "data": {
    "call_id": "some_unique_id",
    "sip_headers": [
      { "name": "From", "value": "sip:+142555512112@sip.example.com" },
      { "name": "To", "value": "sip:+18005551212@sip.example.com" },
      { "name": "Call-ID", "value": "03782086-4ce9-44bf-8b0d-4e303d2cc590"}
    ]
  }
}

From this webhook, you can accept or reject the call, using the call_id value from the webhook. When accepting the call, you’ll provide the needed configuration (instructions, voice, etc) for the Realtime API session. Once established, you can set up a WebSocket and monitor the session as usual. The APIs to accept, reject, monitor, refer, and hangup the call are documented below.

Accept the call

Use the Accept call endpoint to approve the inbound call and configure the realtime session that will answer it. Send the same parameters you would send in a create client secret request, i.e., ensure the realtime model, voice, tools, or instructions are set before bridging the call to the model.

1
2
3
4
5
6
7
8curl -X POST "https://api.openai.com/v1/realtime/calls/$CALL_ID/accept" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "realtime",
        "model": "gpt-realtime-2.1",
        "instructions": "You are Alex, a friendly concierge for Example Corp."
      }'

The request path must include the call_id from the realtime.call.incoming webhook, and every request requires the Authorization header shown above. The endpoint returns 200 OK once the SIP leg is ringing and the realtime session is being established.

Reject the call

Use the Reject call endpoint to decline an invite when you do not want to handle the incoming call, (e.g., from an unsupported country code.) Supply the call_id path parameter and an optional SIP status_code (e.g., 486 to indicate “busy”) in the JSON body to control the response sent back to the carrier.

1
2
3
4curl -X POST "https://api.openai.com/v1/realtime/calls/$CALL_ID/reject" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status_code": 486}'

If no status code is supplied the API uses 603 Decline by default. A successful request responds with 200 OK after OpenAI delivers the SIP response.

Monitor call events

After you accept a call, open a WebSocket connection to the same session to stream events and issue realtime commands. Note that when connecting to an existing call using the call_id parameter, the model argument is not used (as it has already been configured via the accept endpoint).

WebSocket request

GET wss://api.openai.com/v1/realtime?call_id={call_id}

Query parameters

Headers

• Authorization: Bearer YOUR_API_KEY

The WebSocket behaves exactly like any other Realtime API connection. Send response.create, and other client events to control the call, and listen for server events to track progress. See Webhooks and server-side controls for more information.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import WebSocket from "ws";

const callId = "rtc_u1_9c6574da8b8a41a18da9308f4ad974ce";
const ws = new WebSocket(`wss://api.openai.com/v1/realtime?call_id=${callId}`, {
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
  },
});

ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "response.create",
    })
  );
});

Redirect the call

Transfer an active call using the Refer call endpoint. Provide the call_id as well as the target_uri that should be placed in the SIP Refer-To header (for example tel:+14155550123 or sip:agent@example.com).

1
2
3
4curl -X POST "https://api.openai.com/v1/realtime/calls/$CALL_ID/refer" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_uri": "tel:+14155550123"}'

OpenAI returns 200 OK once the REFER is relayed to your SIP provider. The downstream system handles the rest of the call flow for the caller.

Hang up the call

End the session with the Hang up endpoint when your application should disconnect the caller. This endpoint can be used to terminate both SIP and WebRTC realtime sessions.

curl -X POST "https://api.openai.com/v1/realtime/calls/$CALL_ID/hangup" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

The API responds with 200 OK when it starts tearing down the call.

SIP signaling and media IP ranges

Realtime SIP calls use separate network paths for signaling and media. To ensure proper operation, configure your network to allow signaling and media traffic as described below.

SIP signaling

sip.api.openai.com and sip-eu.api.openai.com are GeoIP-routed endpoints. Your network must allow outbound TCP/TLS traffic to the addresses returned by DNS on port 5061.

SRTP media

The API specifies a separate media IP address and UDP port in the negotiated SDP. Your network must allow bidirectional SRTP traffic over UDP to and from the following CIDRs:

• 13.79.45.80/28
• 23.98.140.64/28
• 40.67.149.176/28
• 40.83.204.240/28

Server examples

The following is an example of a realtime.call.incoming handler. It accepts the call and then logs all the events from the Realtime API.

For the Ruby example, set the OPENAI_API_KEY and OPENAI_WEBHOOK_SECRET environment variables, then install the required dependencies with gem install openai webrick async-websocket.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69from flask import Flask, request, Response, jsonify, make_response
from openai import OpenAI, InvalidWebhookSignatureError
import asyncio
import json
import os
import requests
import time
import threading
import websockets

app = Flask(__name__)
client = OpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])

AUTH_HEADER = {"Authorization": "Bearer " + os.environ["OPENAI_API_KEY"]}

call_accept = {
    "type": "realtime",
    "instructions": "You are a support agent.",
    "model": "gpt-realtime-2.1",
}

response_create = {
    "type": "response.create",
    "response": {
        "instructions": ("Say to the user 'Thank you for calling, how can I help you'")
    },
}


async def websocket_task(call_id):
    try:
        async with websockets.connect(
            "wss://api.openai.com/v1/realtime?call_id=" + call_id,
            additional_headers=AUTH_HEADER,
        ) as websocket:
            await websocket.send(json.dumps(response_create))

            while True:
                response = await websocket.recv()
                print(f"Received from WebSocket: {response}")
    except Exception as e:
        print(f"WebSocket error: {e}")


@app.route("/", methods=["POST"])
def webhook():
    try:
        event = client.webhooks.unwrap(request.data, request.headers)
    except (InvalidWebhookSignatureError, ValueError) as e:
        print("Invalid signature", e)
        return Response("Invalid signature", status=400)

    if event.type == "realtime.call.incoming":
        requests.post(
            "https://api.openai.com/v1/realtime/calls/"
            + event.data.call_id
            + "/accept",
            headers={**AUTH_HEADER, "Content-Type": "application/json"},
            json=call_accept,
        ).raise_for_status()
        threading.Thread(
            target=lambda: asyncio.run(websocket_task(event.data.call_id)),
            daemon=True,
        ).start()
    return Response(status=200)


if __name__ == "__main__":
    app.run(port=8000)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104func handler(client openai.Client) http.Handler {
	var mu sync.Mutex
	type acceptance struct {
		done chan struct{}
		err  error
	}
	calls := make(map[string]*acceptance)
	mux := http.NewServeMux()
	mux.HandleFunc("POST /webhook", func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
		if err != nil {
			http.Error(w, "Invalid webhook body", 400)
			return
		}
		event, err := client.Webhooks.Unwrap(body, r.Header)
		if err != nil {
			http.Error(w, "Invalid webhook signature", 400)
			return
		}
		if event.Type != "realtime.call.incoming" {
			w.WriteHeader(200)
			return
		}
		callID := event.Data.CallID
		mu.Lock()
		attempt, exists := calls[callID]
		if !exists {
			attempt = &acceptance{done: make(chan struct{})}
			calls[callID] = attempt
		}
		mu.Unlock()
		if exists {
			select {
			case <-attempt.done:
			case <-r.Context().Done():
				http.Error(w, "Request canceled", http.StatusRequestTimeout)
				return
			}
		} else {
			// Share this attempt's result only with retries of the same call.
			// Persist accepted call IDs in production for deduplication across restarts.
			attempt.err = client.Realtime.Calls.Accept(r.Context(), callID, realtime.CallAcceptParams{
				RealtimeSessionCreateRequest: realtime.RealtimeSessionCreateRequestParam{
					Model:        "gpt-realtime-2.1",
					Instructions: openai.String("You are a helpful support agent."),
				},
			})
			mu.Lock()
			if attempt.err != nil {
				delete(calls, callID) // Allow a later delivery to retry a failed attempt.
			}
			close(attempt.done)
			mu.Unlock()
			if attempt.err == nil {
				go func() {
					if err := greetCaller(client, callID); err != nil {
						log.Print("Call greeting failed: ", err)
					}
				}()
			}
		}
		if attempt.err != nil {
			http.Error(w, "Could not accept call", 502)
			return
		}
		w.WriteHeader(200)
	})
	return mux
}

func greetCaller(client openai.Client, callID string) error {
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
	defer cancel()
	conn, err := client.Realtime.Connect(ctx, realtime.RealtimeConnectionOptions{}, option.WithQuery("call_id", callID))
	if err != nil {
		return err
	}
	defer conn.Close()
	if err := conn.Send(ctx, realtime.RealtimeClientEventUnionParam{
		OfResponseCreate: &realtime.ResponseCreateEventParam{
			Response: realtime.RealtimeResponseCreateParams{
				Instructions:     openai.String("Thank the caller and ask how you can help."),
				OutputModalities: []string{"audio"},
			},
		},
	}); err != nil {
		return err
	}
	for {
		event, err := conn.Recv(ctx)
		if err != nil {
			return err
		}
		if event.Type == "error" {
			return fmt.Errorf("Realtime API error: %s", event.OfRealtimeErrorEvent.Error.Message)
		}
		if event.Type == "response.done" {
			if event.OfResponseDoneEvent.Response.Status != "completed" {
				return fmt.Errorf("greeting did not complete")
			}
			return nil
		}
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61require "openai"
require "webrick"

client = OpenAI::Client.new(webhook_secret: ENV.fetch("OPENAI_WEBHOOK_SECRET"))
server = WEBrick::HTTPServer.new(
  BindAddress: "127.0.0.1",
  Port: Integer(ENV.fetch("OPENAI_WEBHOOK_PORT", "8000")),
  Logger: WEBrick::Log.new($stderr, WEBrick::BasicLog::WARN),
  AccessLog: []
)
sideband_workers = []

server.mount_proc("/webhook") do |request, response|
  if request.request_method != "POST"
    response.status = 405
    next
  end

  headers = request.header.transform_values(&:first)
  event = client.webhooks.unwrap(request.body, headers)

  if event.is_a?(OpenAI::Models::Webhooks::RealtimeCallIncomingWebhookEvent)
    call_id = event.data.call_id
    sideband_workers.select!(&:alive?)
    sideband_workers << Thread.new(call_id) do |active_call_id|
      client.realtime.calls.accept(
        active_call_id,
        type: :realtime,
        model: "gpt-realtime-2.1",
        instructions: "You are a helpful support agent."
      )

      client.realtime.connect_to_call(call_id: active_call_id) do |connection|
        connection.response.create(
          instructions: "Thank the caller and ask how you can help."
        )
        connection.each do |server_event|
          puts "Realtime event: #{server_event.type}"
        end
      end
    end
  end

  response.status = 200
  response.body = "ok"
rescue OpenAI::Errors::InvalidWebhookSignatureError, ArgumentError
  response.status = 400
  response.body = "Invalid signature"
ensure
  server.shutdown if ENV["OPENAI_WEBHOOK_EXIT_AFTER_REQUEST"] == "1"
end

Signal.trap("INT") do
  sideband_workers.each(&:kill)
  server.shutdown
end
port = server.listeners.first.addr[1]
puts "Webhook server listening on http://127.0.0.1:#{port}/webhook"
$stdout.flush
server.start
sideband_workers.each(&:join)

Next steps

Now that you’ve connected over SIP, use the left navigation or click into these pages to start building your realtime application.

• Realtime prompting guide
• Managing conversations
• Webhooks and server-side controls
• Managing costs
• Realtime transcription

Additional Resources

• JavaScript demo
• Connect the Realtime SIP Connector to Twilio Elastic SIP Trunking