|
1 | 1 | --- |
2 | | -author: aakanmu |
| 2 | +author: sloanster |
3 | 3 | ms.service: azure-communication-services |
4 | 4 | ms.topic: include |
5 | | -ms.date: 05/14/2024 |
6 | | -ms.author: aakanmu |
| 5 | +ms.date: 09/13/2024 |
| 6 | +ms.author: micahvivion |
7 | 7 | --- |
8 | | -[!INCLUDE [Install SDK](../install-sdk/install-sdk-web.md)] |
9 | 8 |
|
10 | | -## Place a call with contextual Information |
| 9 | +## Technical parameters |
| 10 | +The calling SDK supports adding up to 5 custom SIP headers and 1000 custom VOIP headers. Additionally, developers can include a dedicated User-To-User header as part of SIP headers list. |
11 | 11 |
|
12 | | -```js |
13 | | -// Set up customContext |
14 | | -this.callOptions.customContext = { |
15 | | - userToUser: <USER_TO_USER_VALUE>, |
16 | | - xHeaders: [ |
17 | | - { key: <CUSTOM_HEADER_KEY>, value: <CUSTOM_HEADER_VALUE> }, |
18 | | - ] |
19 | | -}; |
20 | | -``` |
21 | | -For a "1:1" call to a user, use the following code: |
| 12 | +The maximum length of a SIP header key is 64 chars, including the X-MS-Custom prefix. Due note that when the SIP header is added the calling SDK will automatically add the ‘X-MS-Custom-’ prefix (which can be seeing if you inspect the SIP header with packet inspector). |
22 | 13 |
|
23 | | -```js |
24 | | -const userId = { communicationUserId: 'ACS_USER_ID' }; |
25 | | -this.currentCall = this.callAgent.startCall([userId], this.callOptions); |
26 | | -``` |
| 14 | +The SIP header key may consist of alphanumeric characters and a few selected symbols which include `.`, `!`, `%`, `*`, `_`, `+`, `~`, `-`. The maximum length of SIP header value is 256 chars. The same limitations apply when configuring the SIP headers on your SBC. The SIP header value may consist of alphanumeric characters and a few selected symbols which include `=`, `;`, `.`, `!`, `%`, `*`, `_`, `+`, `~`, `-`. |
27 | 15 |
|
28 | | -To place a call to a public switched telephone network (PSTN), use the `startCall` method on `callAgent` and pass the recipient's `PhoneNumberIdentifier`. Your Communication Services resource must be configured to allow PSTN calling. |
| 16 | +The maximum length of a VOIP header key is 64 chars. The maximum length of VOIP header value is 1024 chars. |
29 | 17 |
|
30 | | -When you call a PSTN number, specify your alternate caller ID. An alternate caller ID is a phone number (based on the E.164 standard) that identifies the caller in a PSTN call. It's the phone number the call recipient sees for an incoming call. |
31 | | - |
32 | | -For a 1:1 call to a PSTN number, use the following code: |
33 | | -```js |
34 | | -const phoneNumber = { phoneNumber: <ACS_PHONE_NUMBER> }; |
35 | | -this.callOptions.alternateCallerId = { phoneNumber: <ALTERNATE_CALLER_ID>} |
36 | | -this.currentCall = this.callAgent.startCall([phoneNumber], this.callOptions); |
37 | | -``` |
| 18 | +When adding these custom headers as a developer you can choose to add only SIP headers, only VoIP headers or both can be included. |
38 | 19 |
|
39 | 20 | > [!NOTE] |
40 | | -> Passing contextual information in group call and add participant scenarios are not supported |
| 21 | +> Currently, adding custom User-to-User Information headers is only supported when initiating a 1:1 call. Passing User-to-User Information headers in group calls is not currently supported. To work around this after starting the 1:1 call, you can include additional participants while maintaining the User-to-User Information within the calls. |
41 | 22 |
|
42 | | -## Receive an incoming call |
43 | 23 |
|
44 | | -The `callAgent` instance emits an `incomingCall` event when the logged-in identity receives an incoming call. To listen to this event and extract contextual info, subscribe by using one of these options: |
| 24 | +## Place a call with User-to-User Information (UUI) data |
45 | 25 |
|
46 | 26 | ```js |
47 | | -const incomingCallHandler = async (args: { incomingCall: IncomingCall }) => { |
48 | | - const incomingCall = args.incomingCall; |
49 | | - |
50 | | - // receiving customContext |
51 | | - const customContext = args.incomingCall.customContext; |
52 | | - |
53 | | - // Get incoming call ID |
54 | | - var incomingCallId = incomingCall.id |
55 | | - |
56 | | - // Get information about this Call. This API is provided as a preview for developers |
57 | | - // and may change based on feedback that we receive. Do not use this API in a production environment. |
58 | | - // To use this api please use 'beta' release of Azure Communication Services Calling Web SDK |
59 | | - var callInfo = incomingCall.info; |
60 | | - |
61 | | - // Get information about caller |
62 | | - var callerInfo = incomingCall.callerInfo |
| 27 | +// Setting custom context UUI Headers |
| 28 | +const callOptions = { |
| 29 | + customContext: { |
| 30 | + voipHeaders: [ |
| 31 | + {key: 'voip-key-1', value: 'voip-value-1'}, |
| 32 | + {key: 'voip-key-2', value: 'voip-value-2'} |
| 33 | + ], |
| 34 | + |
| 35 | + sipHeaders: [ |
| 36 | + {key: 'sip-key-1', value: 'sip-value-1'}, |
| 37 | + {key: 'sip-key-2', value: 'sip-value-2'} |
| 38 | + ], |
| 39 | + userToUser: 'userToUserHeader', |
| 40 | + }, |
| 41 | +}; |
| 42 | +}); |
| 43 | +``` |
63 | 44 |
|
64 | | - // Accept the call |
65 | | - var call = await incomingCall.accept(); |
66 | 45 |
|
67 | | - // Reject the call |
68 | | - incomingCall.reject(); |
| 46 | +## Read and parse User-to-User Information headers in a call |
69 | 47 |
|
70 | | - // Subscribe to callEnded event and get the call end reason |
71 | | - incomingCall.on('callEnded', args => { |
72 | | - console.log(args.callEndReason); |
73 | | - }); |
| 48 | +The `callAgent` instance emits an `incomingCall` event when the logged-in identity receives an incoming call. To listen to this event and extract contextual info, subscribe by using one of these options: |
74 | 49 |
|
75 | | - // callEndReason is also a property of IncomingCall |
76 | | - var callEndReason = incomingCall.callEndReason; |
77 | | -}; |
78 | | -callAgentInstance.on('incomingCall', incomingCallHandler); |
79 | | -``` |
| 50 | +```js |
| 51 | +let info = ''; |
| 52 | + |
| 53 | +callAgent.on("incomingCall", (args) => { |
| 54 | + const incomingCall = args.incomingCall; |
| 55 | + if (incomingCall.customContext) { |
| 56 | + if (incomingCall.customContext.userToUser) { |
| 57 | + info += `userToUser: '${incomingCall.customContext.userToUser}'\n`; |
| 58 | + } |
| 59 | + if (incomingCall.customContext.sipHeaders) { |
| 60 | + incomingCall.customContext.sipHeaders.forEach(header => info += `sip: ${header.key}: '${header.value}'\n`); |
| 61 | + } |
| 62 | + if (incomingCall.customContext.voipHeaders) { |
| 63 | + incomingCall.customContext.voipHeaders.forEach(header => info += `voip: ${header.key}: '${header.value}'\n`); |
| 64 | + } |
| 65 | + } |
| 66 | +}); |
| 67 | +``` |
0 commit comments