SIP Basics

This guide provides an introduction to the Session Initiation Protocol (SIP) as implemented in Parrot, following RFC 3261, with detailed flow diagrams showing how SIP works in practice.

What is SIP?

SIP (Session Initiation Protocol) is a signaling protocol used for initiating, maintaining, and terminating real-time sessions that include voice, video and messaging applications. It is defined in RFC 3261.

Basic SIP Call Flow

This flow demonstrates a basic SIP session establishment as described in RFC 3665 Section 3.1:

sequenceDiagram
    participant Alice as Alice 192.168.1.100
    participant Proxy as SIP Proxy sip.example.com
    participant Location as Location Service
    participant Bob as Bob 10.0.0.50
    
    Note over Alice: Wants to call bob@example.com
    
    Alice->>Proxy: INVITE sip:bob@example.com
    Note right of Alice: Via: SIP/2.0/UDP 192.168.1.100:5060\nFrom: alice@example.com\nTo: bob@example.com\nCall-ID: 12345@192.168.1.100
    
    Proxy->>Location: Query bob@example.com
    Location->>Proxy: Contact: sip:bob@10.0.0.50
    
    Proxy->>Bob: INVITE sip:bob@10.0.0.50
    Note right of Proxy: Via: SIP/2.0/UDP proxy.example.com\nVia: SIP/2.0/UDP 192.168.1.100:5060\nRecord-Route: sip:proxy.example.com
    
    Bob->>Proxy: 180 Ringing
    Proxy->>Alice: 180 Ringing
    
    Note over Bob: User answers
    
    Bob->>Proxy: 200 OK (+ SDP)
    Note left of Bob: Contact: sip:bob@10.0.0.50\nContent-Type: application/sdp
    
    Proxy->>Alice: 200 OK (+ SDP)
    
    Alice->>Proxy: ACK
    Proxy->>Bob: ACK
    
    Note over Alice,Bob: RTP Media Flow (Direct)
    Alice<->Bob: Voice/Video (RTP)
    
    Note over Alice: Hangs up
    
    Alice->>Proxy: BYE
    Proxy->>Bob: BYE
    Bob->>Proxy: 200 OK
    Proxy->>Alice: 200 OK

SIP Registration Flow

SIP registration is specified in RFC 3261 Section 10:

sequenceDiagram
    participant UA as User Agent (Alice's Phone)
    participant Registrar as Registrar Server
    participant Auth as Authentication Service
    participant Location as Location Database
    
    UA->>Registrar: REGISTER sip:example.com
    Note right of UA: From: alice@example.com\nTo: alice@example.com\nContact: sip:alice@192.168.1.100\nExpires: 3600
    
    Registrar->>UA: 401 Unauthorized
    Note left of Registrar: WWW-Authenticate: Digest\nrealm=example.com\nnonce=84a4cc6f3082121f
    
    UA->>UA: Calculate Digest Response
    
    UA->>Registrar: REGISTER sip:example.com
    Note right of UA: Authorization: Digest\nusername=alice\nrealm=example.com\nnonce=84a4cc6f3082121f\nresponse=7587245234b3434cc3412
    
    Registrar->>Auth: Verify Credentials
    Auth->>Registrar: OK
    
    Registrar->>Location: Store Binding
    Note right of Registrar: AOR: alice@example.com\nContact: sip:alice@192.168.1.100\nExpires: 3600
    
    Location->>Registrar: Stored
    
    Registrar->>UA: 200 OK
    Note left of Registrar: Contact: sip:alice@192.168.1.100 expires=3600

SDP Negotiation in Detail

Session Description Protocol (SDP) negotiation follows RFC 4566 for SDP format and RFC 3264 for offer/answer model:

sequenceDiagram
    participant Alice as Alice
    participant Handler as Parrot Handler
    participant Bob as Bob
    
    Note over Alice: SDP Offer
    Alice->>Handler: INVITE with SDP
    Note right of Alice: v=0\no=alice 2890844526 IN IP4 192.168.1.100\ns=Session\nc=IN IP4 192.168.1.100\nt=0 0\nm=audio 49170 RTP/AVP 0 8 97\na=rtpmap:0 PCMU/8000\na=rtpmap:8 PCMA/8000\na=rtpmap:97 opus/48000
    
    Handler->>Handler: Parse Offer\nSelect Codecs
    
    Handler->>Bob: 200 OK with SDP Answer
    Note right of Handler: v=0\no=bob 2890844527 IN IP4 10.0.0.50\ns=Session\nc=IN IP4 10.0.0.50\nt=0 0\nm=audio 49172 RTP/AVP 0\na=rtpmap:0 PCMU/8000
    
    Note over Alice,Bob: Negotiated: PCMU codec\nAlice sends to 10.0.0.50:49172\nBob sends to 192.168.1.100:49170
    
    Alice->>Bob: RTP PCMU @49172
    Bob->>Alice: RTP PCMU @49170

SIP Transaction State Machines

These state machines are precisely defined in RFC 3261 Section 17:

Server Transaction (INVITE)

As specified in RFC 3261 Section 17.2.1:

stateDiagram-v2
    [*] --> Trying: INVITE received
    
    Trying --> Proceeding: Send 1xx response
    Trying --> Completed: Send final response (300-699)
    
    Proceeding --> Proceeding: Send 1xx response
    Proceeding --> Completed: Send final response (300-699)
    
    Completed --> Confirmed: ACK received
    Completed --> Terminated: Timer H expires (no ACK)
    
    Confirmed --> Terminated: Timer I expires
    
    note right of Trying: Initial state\nStart Timer H
    note right of Proceeding: Provisional responses sent\nCan send multiple 1xx
    note right of Completed: Final response sent\nWaiting for ACK
    note right of Confirmed: ACK received\nStart Timer I (5s)
    note right of Terminated: Transaction ends\nCleanup resources

Client Transaction (INVITE)

As specified in RFC 3261 Section 17.1.1:

stateDiagram-v2
    [*] --> Calling: Send INVITE
    
    Calling --> Proceeding: Receive 1xx response
    Calling --> Completed: Receive 300-699 response
    Calling --> Terminated: Receive 2xx response
    
    Proceeding --> Proceeding: Receive 1xx response
    Proceeding --> Completed: Receive 300-699 response
    Proceeding --> Terminated: Receive 2xx response
    
    Completed --> Terminated: Timer D expires
    
    note right of Calling: INVITE sent\nStart Timer A & B
    note right of Proceeding: Provisional received\nCancel Timer A & B
    note right of Completed: Error response\nSend ACK, start Timer D
    note right of Terminated: Success (2xx) or timeout\nTransaction ends

Server Transaction (Non-INVITE)

As specified in RFC 3261 Section 17.2.2:

stateDiagram-v2
    [*] --> Trying: Request received
    
    Trying --> Proceeding: Send 1xx response
    Trying --> Completed: Send final response
    
    Proceeding --> Proceeding: Send 1xx response
    Proceeding --> Completed: Send final response
    
    Completed --> Terminated: Timer J expires
    
    note right of Trying: BYE, OPTIONS, etc.\nNo special timers
    note right of Proceeding: Provisional sent\nRarely used
    note right of Completed: Final response sent\nStart Timer J (32s)
    note right of Terminated: Transaction ends

Client Transaction (Non-INVITE)

As specified in RFC 3261 Section 17.1.2:

stateDiagram-v2
    [*] --> Trying: Send request
    
    Trying --> Proceeding: Receive 1xx response
    Trying --> Completed: Receive final response
    
    Proceeding --> Proceeding: Receive 1xx response
    Proceeding --> Completed: Receive final response
    
    Completed --> Terminated: Timer K expires
    
    note right of Trying: Request sent\nStart Timer E & F
    note right of Proceeding: Provisional received\nTimer E continues
    note right of Completed: Final response\nStart Timer K (5s)
    note right of Terminated: Transaction ends

CANCEL Flow

The CANCEL method is defined in RFC 3261 Section 9:

sequenceDiagram
    participant Alice as Alice
    participant Proxy as Proxy
    participant Bob as Bob
    
    Alice->>Proxy: INVITE
    Proxy->>Bob: INVITE
    Bob->>Proxy: 180 Ringing
    Proxy->>Alice: 180 Ringing
    
    Note over Alice: User cancels call
    
    Alice->>Proxy: CANCEL
    Note right of Alice: Same Call-ID\nSame From tag\nSame Request-URI
    
    Proxy->>Alice: 200 OK (CANCEL)
    
    Proxy->>Bob: CANCEL
    Bob->>Proxy: 200 OK (CANCEL)
    Bob->>Proxy: 487 Request Terminated
    Proxy->>Alice: 487 Request Terminated
    
    Alice->>Proxy: ACK
    Proxy->>Bob: ACK

Forking Proxy Flow

Forking proxy behavior is specified in RFC 3261 Section 16.7:

sequenceDiagram
    participant Alice as Alice
    participant Proxy as Forking Proxy
    participant Bob1 as Bob (Office)
    participant Bob2 as Bob (Mobile)
    participant Bob3 as Bob (Home)
    
    Alice->>Proxy: INVITE bob@example.com
    
    par Parallel Forking
        Proxy->>Bob1: INVITE (branch-1)
    and
        Proxy->>Bob2: INVITE (branch-2)
    and
        Proxy->>Bob3: INVITE (branch-3)
    end
    
    Bob1->>Proxy: 180 Ringing
    Proxy->>Alice: 180 Ringing
    
    Bob2->>Proxy: 180 Ringing
    Note over Proxy: Suppressed (already sent 180)
    
    Bob3->>Proxy: 486 Busy Here
    
    Bob2->>Proxy: 200 OK
    
    Note over Proxy: Cancel other branches
    
    Proxy->>Bob1: CANCEL
    Bob1->>Proxy: 200 OK (CANCEL)
    Bob1->>Proxy: 487 Request Terminated
    
    Proxy->>Alice: 200 OK (from Bob2)
    
    Alice->>Proxy: ACK
    Proxy->>Bob2: ACK
    
    Note over Alice,Bob2: Call established with Mobile

Early Media Flow

Early media is discussed in RFC 3960:

sequenceDiagram
    participant Caller as Caller
    participant PBX as PBX/IVR
    participant Callee as Callee
    
    Caller->>PBX: INVITE
    PBX->>PBX: Start IVR
    
    PBX->>Caller: 183 Session Progress
    Note right of PBX: SDP with media info\na=sendonly
    
    Note over Caller,PBX: Early Media (One-way)
    PBX-->>Caller: RTP (Announcement)
    Note left of PBX: Please wait while\nwe connect your call...
    
    PBX->>Callee: INVITE
    Callee->>PBX: 180 Ringing
    
    Note over Caller,PBX: Early Media continues
    PBX-->>Caller: RTP (Ring tone)
    
    Callee->>PBX: 200 OK
    PBX->>Caller: 200 OK
    
    Caller->>PBX: ACK
    PBX->>Callee: ACK
    
    Note over Caller,Callee: Regular Media (Two-way)
    Caller<->PBX: RTP
    PBX<->Callee: RTP

REFER (Call Transfer) Flow

The REFER method is specified in RFC 3515:

sequenceDiagram
    participant A as Alice
    participant B as Bob
    participant C as Carol
    
    Note over A,B: Existing call
    A<->B: RTP Media
    
    Note over B: Bob transfers to Carol
    
    B->>A: REFER sip:carol@example.com
    Note right of B: Refer-To: sip:carol@example.com
    
    A->>B: 202 Accepted
    
    A->>B: NOTIFY
    Note right of A: Event: refer\nSubscription-State: active\nContent-Type: message/sipfrag\nSIP/2.0 100 Trying
    
    B->>A: 200 OK
    
    A->>C: INVITE
    Note right of A: Referred-By: sip:bob@example.com
    
    C->>A: 200 OK
    A->>C: ACK
    
    A->>B: NOTIFY
    Note right of A: Event: refer\nSubscription-State: terminated\nContent-Type: message/sipfrag\nSIP/2.0 200 OK
    
    B->>A: 200 OK
    
    A->>B: BYE
    B->>A: 200 OK
    
    Note over A,C: New call established
    A<->C: RTP Media

SIP Headers Explained

SIP header fields are defined in RFC 3261 Section 20:

Via Header Path

Via header processing is specified in RFC 3261 Section 8.1.1.7:

graph LR
    subgraph "Request Path"
        A[Alice] -->|Via: A| P1[Proxy 1]
        P1 -->|Via: P1 Via: A| P2[Proxy 2]
        P2 -->|Via: P2 Via: P1 Via: A| B[Bob]
    end
    
    subgraph "Response Path"
        B2[Bob] -->|Remove Via: P2| P22[Proxy 2]
        P22 -->|Remove Via: P1| P12[Proxy 1]
        P12 -->|Remove Via: A| A2[Alice]
    end

Record-Route and Route Headers

Record-Route mechanism is defined in RFC 3261 Section 16.6:

sequenceDiagram
    participant A as Alice
    participant P1 as Proxy 1
    participant P2 as Proxy 2
    participant B as Bob
    
    A->>P1: INVITE
    Note right of A: No Route headers
    
    P1->>P2: INVITE
    Note right of P1: Record-Route: sip:p1.com lr
    
    P2->>B: INVITE
    Note right of P2: Record-Route: sip:p2.com lr\nRecord-Route: sip:p1.com lr
    
    B->>P2: 200 OK
    Note left of B: Record-Route: sip:p2.com lr\nRecord-Route: sip:p1.com lr
    
    P2->>P1: 200 OK
    P1->>A: 200 OK
    
    Note over A: Stores Route Set:\n1. sip:p1.com lr\n2. sip:p2.com lr
    
    A->>P1: ACK
    Note right of A: Route: sip:p1.com lr\nRoute: sip:p2.com lr
    
    P1->>P2: ACK
    Note right of P1: Route: sip:p2.com lr
    
    P2->>B: ACK
    Note right of P2: No Route headers

Using Parrot for SIP

Parrot handles all these complex flows automatically. You simply implement the Handler behavior:

defmodule MyHandler do
  @behaviour Parrot.SipHandler
  
  def handle_invite(message, state) do
    # Parrot handles:
    # - Transaction state machines
    # - Retransmissions
    # - Timer management
    # - Response routing
    # - Dialog state
    
    # You handle:
    # - Business logic
    # - Media decisions
    # - User interaction
    
    {:respond, 200, "OK", headers, sdp, state}
  end
end

Parrot abstracts the protocol complexity while giving you full control over application behavior.