Adding a custom struct to use for call end hooks (#396)

* adding a custom struct to use for call end hooks
The struct has project id, the scl call id generated by livekit/livekit and the protocol level sip call id

* Assigning the right values to the identifiers

* Improving the tests a bit

* Correctly passing the ProjectID at the end of the call

* Using Session End instead of CallEnd to be more accurate. Also handling call drop use cases before the connection was established

* Ensuring project id is available prior to call connection

* Changes from PR feedback

* Pulling in latest version of protocol to add SipCallId to SipCall

Author: nishadmusthafa

go.mod

@@ -12,7 +12,7 @@ require (
 	github.com/livekit/mageutil v0.0.0-20250511045019-0f1ff63f7731
 	github.com/livekit/media-sdk v0.0.0-20250620175140-c86da91c22a2
 	github.com/livekit/mediatransportutil v0.0.0-20250519131108-fb90f5acfded
-	github.com/livekit/protocol v1.39.0
+	github.com/livekit/protocol v1.39.4-0.20250626001605-256d96948009
 	github.com/livekit/psrpc v0.6.1-0.20250511053145-465289d72c3c
 	github.com/livekit/server-sdk-go/v2 v2.9.2-0.20250606164215-22b67ed30bd9
 	github.com/livekit/sipgo v0.13.2-0.20250601220430-a77cc3f220fb

go.sum

@@ -127,8 +127,8 @@ github.com/livekit/media-sdk v0.0.0-20250620175140-c86da91c22a2 h1:uHDhc7gk5Wcxd
 github.com/livekit/media-sdk v0.0.0-20250620175140-c86da91c22a2/go.mod h1:7ssWiG+U4xnbvLih9WiZbhQP6zIKMjgXdUtIE1bm/E8=
 github.com/livekit/mediatransportutil v0.0.0-20250519131108-fb90f5acfded h1:ylZPdnlX1RW9Z15SD4mp87vT2D2shsk0hpLJwSPcq3g=
 github.com/livekit/mediatransportutil v0.0.0-20250519131108-fb90f5acfded/go.mod h1:mSNtYzSf6iY9xM3UX42VEI+STHvMgHmrYzEHPcdhB8A=
-github.com/livekit/protocol v1.39.0 h1:xmpkEr0+29xiAu+Z/m7CmsGuLKHf5ba5+5rkGdMdZEY=
-github.com/livekit/protocol v1.39.0/go.mod h1:6HPISM0bkTXTk9RIaQTCe0IDbomBPz7Jwp+N3w5sqL0=
+github.com/livekit/protocol v1.39.4-0.20250626001605-256d96948009 h1:2q0bh85UfRSD4eZqB+EboPH1V7ikeX9MiLKRVpIz1yA=
+github.com/livekit/protocol v1.39.4-0.20250626001605-256d96948009/go.mod h1:6HPISM0bkTXTk9RIaQTCe0IDbomBPz7Jwp+N3w5sqL0=
 github.com/livekit/psrpc v0.6.1-0.20250511053145-465289d72c3c h1:WwEr0YBejYbKzk8LSaO9h8h0G9MnE7shyDu8yXQWmEc=
 github.com/livekit/psrpc v0.6.1-0.20250511053145-465289d72c3c/go.mod h1:kmD+AZPkWu0MaXIMv57jhNlbiSZZ/Jx4bzlxBDVmJes=
 github.com/livekit/server-sdk-go/v2 v2.9.2-0.20250606164215-22b67ed30bd9 h1:PffMsBrfW7KPOHy/P6I939+xqTbJBWQtmbx89SWeLkU=

pkg/service/service.go

@@ -254,6 +254,6 @@ func (s *Service) DeregisterTransferSIPParticipantTopic(sipCallId string) {
 	}
 }
 
-func (s *Service) OnCallEnd(ctx context.Context, callInfo *livekit.SIPCallInfo, reason string) {
+func (s *Service) OnSessionEnd(ctx context.Context, callIdentifier *sip.CallIdentifier, callInfo *livekit.SIPCallInfo, reason string) {
 	s.log.Infow("SIP call ended", "callID", callInfo.CallId, "reason", reason)
 }

pkg/sip/client.go

@@ -223,7 +223,7 @@ func (c *Client) createSIPParticipant(ctx context.Context, req *rpc.InternalCrea
 		mediaEncryption: enc,
 	}
 	log.Infow("Creating SIP participant")
-	call, err := c.newCall(ctx, c.conf, log, LocalTag(req.SipCallId), roomConf, sipConf, state)
+	call, err := c.newCall(ctx, c.conf, log, LocalTag(req.SipCallId), roomConf, sipConf, state, req.ProjectId)
 	if err != nil {
 		return nil, err
 	}

pkg/sip/inbound.go

@@ -376,6 +376,7 @@ type inboundCall struct {
 	started     core.Fuse
 	stats       Stats
 	jitterBuf   bool
+	projectID   string
 }
 
 func (s *Server) newInboundCall(
@@ -398,6 +399,7 @@ func (s *Server) newInboundCall(
 		extraAttrs: extra,
 		dtmf:       make(chan dtmf.Event, 10),
 		jitterBuf:  SelectValueBool(s.conf.EnableJitterBuffer, s.conf.EnableJitterBufferProb),
+		projectID:  "", // Will be set in handleInvite when available
 	}
 	// we need it created earlier so that the audio mixer is available for pin prompts
 	c.lkRoom = NewRoom(log, &c.stats.Room)
@@ -416,6 +418,11 @@ func (c *inboundCall) handleInvite(ctx context.Context, req *sip.Request, trunkI
 	defer c.mon.CallEnd()
 	defer c.close(true, callDropped, "other")
 
+	// Extract and store the SIP call ID from the request
+	if h := req.CallID(); h != nil {
+		c.call.SipCallId = h.Value()
+	}
+
 	c.cc.StartRinging()
 	// Send initial request. In the best case scenario, we will immediately get a room name to join.
 	// Otherwise, we could even learn that this number is not allowed and reject the call, or ask for pin if required.
@@ -427,6 +434,7 @@ func (c *inboundCall) handleInvite(ctx context.Context, req *sip.Request, trunkI
 	})
 	if disp.ProjectID != "" {
 		c.log = c.log.WithValues("projectID", disp.ProjectID)
+		c.projectID = disp.ProjectID
 	}
 	if disp.TrunkID != "" {
 		c.log = c.log.WithValues("sipTrunk", disp.TrunkID)
@@ -765,6 +773,7 @@ func (c *inboundCall) pinPrompt(ctx context.Context, trunkID string) (disp CallD
 				})
 				if disp.ProjectID != "" {
 					c.log = c.log.WithValues("projectID", disp.ProjectID)
+					c.projectID = disp.ProjectID
 				}
 				if disp.TrunkID != "" {
 					c.log = c.log.WithValues("sipTrunk", disp.TrunkID)
@@ -827,7 +836,11 @@ func (c *inboundCall) close(error bool, status CallStatus, reason string) {
 
 	// Call the handler asynchronously to avoid blocking
 	if c.s.handler != nil {
-		go c.s.handler.OnCallEnd(context.Background(), c.state.callInfo, reason)
+		go c.s.handler.OnSessionEnd(context.Background(), &CallIdentifier{
+			ProjectID: c.projectID,
+			CallID:    c.call.LkCallId,
+			SipCallID: c.call.SipCallId,
+		}, c.state.callInfo, reason)
 	}
 
 	c.cancel()

pkg/sip/outbound.go

@@ -75,6 +75,7 @@ type outboundCall struct {
 	closing   core.Fuse
 	stats     Stats
 	jitterBuf bool
+	projectID string
 
 	mu       sync.RWMutex
 	mon      *stats.CallMonitor
@@ -83,7 +84,7 @@ type outboundCall struct {
 	sipConf  sipOutboundConfig
 }
 
-func (c *Client) newCall(ctx context.Context, conf *config.Config, log logger.Logger, id LocalTag, room RoomConfig, sipConf sipOutboundConfig, state *CallState) (*outboundCall, error) {
+func (c *Client) newCall(ctx context.Context, conf *config.Config, log logger.Logger, id LocalTag, room RoomConfig, sipConf sipOutboundConfig, state *CallState, projectID string) (*outboundCall, error) {
 	if sipConf.maxCallDuration <= 0 || sipConf.maxCallDuration > maxCallDuration {
 		sipConf.maxCallDuration = maxCallDuration
 	}
@@ -104,6 +105,7 @@ func (c *Client) newCall(ctx context.Context, conf *config.Config, log logger.Lo
 		sipConf:   sipConf,
 		state:     state,
 		jitterBuf: jitterBuf,
+		projectID: projectID,
 	}
 	call.log = call.log.WithValues("jitterBuf", call.jitterBuf)
 	call.cc = c.newOutbound(log, id, URI{
@@ -302,7 +304,11 @@ func (c *outboundCall) close(err error, status CallStatus, description string, r
 
 		// Call the handler asynchronously to avoid blocking
 		if c.c.handler != nil {
-			go c.c.handler.OnCallEnd(context.Background(), c.state.callInfo, description)
+			go c.c.handler.OnSessionEnd(context.Background(), &CallIdentifier{
+				ProjectID: c.projectID,
+				CallID:    c.state.callInfo.CallId,
+				SipCallID: c.cc.CallID(),
+			}, c.state.callInfo, description)
 		}
 	})
 }

pkg/sip/server.go

@@ -99,6 +99,12 @@ type CallDispatch struct {
 	MediaEncryption     livekit.SIPMediaEncryption
 }
 
+type CallIdentifier struct {
+	ProjectID string
+	CallID    string
+	SipCallID string
+}
+
 type Handler interface {
 	GetAuthCredentials(ctx context.Context, call *rpc.SIPCall) (AuthInfo, error)
 	DispatchCall(ctx context.Context, info *CallInfo) CallDispatch
@@ -107,7 +113,7 @@ type Handler interface {
 	RegisterTransferSIPParticipantTopic(sipCallId string) error
 	DeregisterTransferSIPParticipantTopic(sipCallId string)
 
-	OnCallEnd(ctx context.Context, callInfo *livekit.SIPCallInfo, reason string)
+	OnSessionEnd(ctx context.Context, callIdentifier *CallIdentifier, callInfo *livekit.SIPCallInfo, reason string)
 }
 
 type Server struct {

pkg/sip/service_test.go

@@ -57,7 +57,7 @@ func expectNoResponse(t *testing.T, tx sip.ClientTransaction) {
 type TestHandler struct {
 	GetAuthCredentialsFunc func(ctx context.Context, call *rpc.SIPCall) (AuthInfo, error)
 	DispatchCallFunc       func(ctx context.Context, info *CallInfo) CallDispatch
-	OnCallEndFunc          func(ctx context.Context, callInfo *livekit.SIPCallInfo, reason string)
+	OnSessionEndFunc       func(ctx context.Context, callIdentifier *CallIdentifier, callInfo *livekit.SIPCallInfo, reason string)
 }
 
 func (h TestHandler) GetAuthCredentials(ctx context.Context, call *rpc.SIPCall) (AuthInfo, error) {
@@ -81,9 +81,9 @@ func (h TestHandler) DeregisterTransferSIPParticipantTopic(sipCallId string) {
 	// no-op
 }
 
-func (h TestHandler) OnCallEnd(ctx context.Context, callInfo *livekit.SIPCallInfo, reason string) {
-	if h.OnCallEndFunc != nil {
-		h.OnCallEndFunc(ctx, callInfo, reason)
+func (h TestHandler) OnSessionEnd(ctx context.Context, callIdentifier *CallIdentifier, callInfo *livekit.SIPCallInfo, reason string) {
+	if h.OnSessionEndFunc != nil {
+		h.OnSessionEndFunc(ctx, callIdentifier, callInfo, reason)
 	}
 }
 
@@ -177,13 +177,16 @@ func TestService_AuthDrop(t *testing.T) {
 	})
 }
 
-func TestService_OnCallEnd(t *testing.T) {
+func TestService_OnSessionEnd(t *testing.T) {
 	const (
-		expectedCallID = "test-call-id"
-		expectedReason = "test-reason"
+		expectedCallID    = "test-call-id"
+		expectedSipCallID = "test-sip-call-id"
+		expectedProjectID = "test-project"
+		expectedReason    = "test-reason"
 	)
 
 	callEnded := make(chan struct{})
+	var receivedCallIdentifier *CallIdentifier
 	var receivedCallInfo *livekit.SIPCallInfo
 	var receivedReason string
 
@@ -202,7 +205,8 @@ func TestService_OnCallEnd(t *testing.T) {
 				},
 			}
 		},
-		OnCallEndFunc: func(ctx context.Context, callInfo *livekit.SIPCallInfo, reason string) {
+		OnSessionEndFunc: func(ctx context.Context, callIdentifier *CallIdentifier, callInfo *livekit.SIPCallInfo, reason string) {
+			receivedCallIdentifier = callIdentifier
 			receivedCallInfo = callInfo
 			receivedReason = reason
 			close(callEnded)
@@ -228,21 +232,37 @@ func TestService_OnCallEnd(t *testing.T) {
 	s.SetHandler(h)
 	require.NoError(t, s.Start())
 
-	// Call OnCallEnd directly
-	h.OnCallEnd(context.Background(), &livekit.SIPCallInfo{
+	// Call OnSessionEnd directly with test data
+	h.OnSessionEnd(context.Background(), &CallIdentifier{
+		ProjectID: expectedProjectID,
+		CallID:    expectedCallID,
+		SipCallID: expectedSipCallID,
+	}, &livekit.SIPCallInfo{
 		CallId: expectedCallID,
+		ParticipantAttributes: map[string]string{
+			"projectID":       expectedProjectID,
+			AttrSIPCallIDFull: expectedSipCallID,
+		},
 	}, expectedReason)
 
-	// Wait for OnCallEnd to be called
+	// Wait for OnSessionEnd to be called
 	select {
 	case <-callEnded:
 		// Success
 	case <-time.After(time.Second):
-		t.Fatal("OnCallEnd was not called")
+		t.Fatal("OnSessionEnd was not called")
 	}
 
-	// Verify the parameters passed to OnCallEnd
+	// Verify the CallIdentifier fields are correctly populated
+	require.NotNil(t, receivedCallIdentifier, "CallIdentifier should not be nil")
+	require.Equal(t, expectedProjectID, receivedCallIdentifier.ProjectID, "CallIdentifier.ProjectID should match")
+	require.Equal(t, expectedCallID, receivedCallIdentifier.CallID, "CallIdentifier.CallID should match")
+	require.Equal(t, expectedSipCallID, receivedCallIdentifier.SipCallID, "CallIdentifier.SipCallID should match")
+
+	// Verify the CallInfo fields
 	require.NotNil(t, receivedCallInfo, "CallInfo should not be nil")
+	require.Equal(t, expectedProjectID, receivedCallInfo.ParticipantAttributes["projectID"], "CallInfo.ParticipantAttributes[projectID] should match")
 	require.Equal(t, expectedCallID, receivedCallInfo.CallId, "CallInfo.CallId should match")
+	require.Equal(t, expectedSipCallID, receivedCallInfo.ParticipantAttributes[AttrSIPCallIDFull], "CallInfo.ParticipantAttributes[sip.callIDFull] should match")
 	require.Equal(t, expectedReason, receivedReason, "Reason should match")
 }