mirror of
https://github.com/jambonz/next-static-site.git
synced 2025-12-19 04:47:44 +00:00
reset yarn lock
This commit is contained in:
kitajchuk
@@ -66,6 +66,9 @@ navi:
|
||||
-
|
||||
path: sip-decline
|
||||
title: sip:decline
|
||||
-
|
||||
path: sip-request
|
||||
title: sip:request
|
||||
-
|
||||
path: sip-refer
|
||||
title: sip:refer
|
||||
@@ -82,6 +85,40 @@ navi:
|
||||
-
|
||||
path: overview
|
||||
title: Overview
|
||||
-
|
||||
path: ws
|
||||
title: Websocket API
|
||||
pages:
|
||||
-
|
||||
path: overview
|
||||
title: Overview
|
||||
-
|
||||
path: session-new
|
||||
title: session:new
|
||||
-
|
||||
path: session-redirect
|
||||
title: session:redirect
|
||||
-
|
||||
path: session-reconnect
|
||||
title: session:reconnect
|
||||
-
|
||||
path: call-status
|
||||
title: call:status
|
||||
-
|
||||
path: verb-hook
|
||||
title: verb:hook
|
||||
-
|
||||
path: verb-status
|
||||
title: verb:status
|
||||
-
|
||||
path: jambonz-error
|
||||
title: jambonz:error
|
||||
-
|
||||
path: ack
|
||||
title: ack
|
||||
-
|
||||
path: command
|
||||
title: command
|
||||
-
|
||||
path: client-sdks
|
||||
title: Client SDKs
|
||||
|
||||
@@ -33,6 +33,7 @@ You can use the following options in the `listen` action:
|
||||
| maxLength | the maximum length of the listened audio stream, in secs | no |
|
||||
| metadata | arbitrary data to add to the JSON payload sent to the remote server when websocket connection is first connected | no |
|
||||
| mixType | "mono" (send single channel), "stereo" (send dual channel of both calls in a bridge), or "mixed" (send audio from both calls in a bridge in a single mixed audio stream) Default: mono | no |
|
||||
| passDtmf | if true, any dtmf digits detected from the caller will be passed over the websocket as text frames in JSON format. The JSON payload will look like this: {"event": "dtmf", "dtmf": "2", "duration": 1600}. Duration is measured in RTP timestamp units. Default: false| no |
|
||||
| playBeep | true, false whether to play a beep at the start of the listen operation. Default: false | no |
|
||||
| sampleRate | sample rate of audio to send (allowable values: 8000, 16000, 24000, 48000, or 64000). Default: 8000 | no |
|
||||
| timeout | the number of seconds of silence that terminates the listen operation.| no |
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
# Webhooks
|
||||
|
||||
jambonz uses JSON payloads that are exchanged in HTTP messages to control calls.
|
||||
jambonz controls calls through the use of JSON payloads that are exchanged either over an HTTP(s) or a websocket connection. When an incoming call for your account is received, jambonz retrieves the URL that you have configured for the application you want to run. If the URL begins with 'http(s)://' jambonz makes an http request to the URL, while if the URL starts with 'ws(s)://' jambonz establishes a websocket connection to that URL. jambonz then sends an initial message describing the incoming call, and your webapp is then responsible for returning a JSON payload that indicates how you want the call handled.
|
||||
|
||||
|
||||
Either way (http or websocket) the details of the JSON payloads are the same. The information below pertains to using HTTP connections; for information describing the websocket interface [see here](/docs/ws).
|
||||
|
||||
When an incoming call for your account is received, jambonz makes an HTTP request to a URL that you have configured and your webapp will then return a response containing a JSON body that indicates how you want the call handled.
|
||||
|
||||
|
||||
@@ -42,5 +42,5 @@ The *eventHook* webhook will contain two parameters: `event` and `call_status`.
|
||||
|
||||
<p class="flex">
|
||||
<a href="/docs/webhooks/sip-decline">Prev: sip:decline</a>
|
||||
<a href="/docs/webhooks/tag">Next: tag</a>
|
||||
<a href="/docs/webhooks/sip-request">Next: sip:refer</a>
|
||||
</p>
|
||||
|
||||
35
markdown/docs/webhooks/sip-request.md
Normal file
35
markdown/docs/webhooks/sip-request.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# sip:request
|
||||
> Added in v0.7.6
|
||||
|
||||
The sip:request action is used to send a SIP INFO, NOTIFY, or MESSAGE request on an established call leg, i.e. an in-dialog request. This allows an application to send arbitrary SIP messages during a call; e.g. to transmit metadata to the calling sip endpoint using a SIP INFO message.
|
||||
|
||||
```json
|
||||
{
|
||||
"verb": "sip:request",
|
||||
"method": "INFO",
|
||||
"headers": {
|
||||
"X-Metadata": "my sip metadata"
|
||||
}
|
||||
"actionHook": "/info"
|
||||
}
|
||||
```
|
||||
|
||||
You can use the following options in the `sip:request` action:
|
||||
|
||||
| option | description | required |
|
||||
| ------------- |-------------| -----|
|
||||
| method |SIP method, should be one of INFO, MESSAGE, or NOTIFY| yes |
|
||||
| headers | an object containing headers (key-value) to include with the SIP request | no |
|
||||
| body | the body of the SIP request, if any | no |
|
||||
| actionHook | a webhook to call when the sip request has completed | no |
|
||||
|
||||
The sip:request verb completes when a response is received from the far end. The actionHook provides the status code of the sip response:
|
||||
|
||||
- `result`: 'success' or 'failed'
|
||||
- `sipStatus`: sip status code of response
|
||||
- `err`: error message, in the case of failure
|
||||
|
||||
<p class="flex">
|
||||
<a href="/docs/webhooks/sip-refer">Prev: sip:refer</a>
|
||||
<a href="/docs/webhooks/tag">Next: tag</a>
|
||||
</p>
|
||||
9
markdown/docs/ws/ack.md
Normal file
9
markdown/docs/ws/ack.md
Normal file
@@ -0,0 +1,9 @@
|
||||
# ack
|
||||
|
||||
An `ack` message is sent by the websocket server to jambonz in response to a `session:new` or `verb:hook` message. The ack message may optionally contain a payload of new instructions for jambonz to execute.
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/jambonz-error">Prev: jambonz:error</a>
|
||||
<a href="/docs/ws/command">Next: command</a>
|
||||
</p>
|
||||
10
markdown/docs/ws/call-status.md
Normal file
10
markdown/docs/ws/call-status.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# call:status
|
||||
|
||||
A `call:status` message is sent by jambonz to the websocket server any time the call status changes
|
||||
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/session-reconnect">Prev: session:reconnect</a>
|
||||
<a href="/docs/ws/verb-hook">Next: verb:hook</a>
|
||||
</p>
|
||||
10
markdown/docs/ws/command.md
Normal file
10
markdown/docs/ws/command.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# command
|
||||
|
||||
A `command` message is sent by the websocket server to jambonz when the server wants to asynchronously provide a new set of instructions to jambonz.
|
||||
|
||||
The app **may** include an `id` property in each of the verbs included in the command; if so, jambonz will send `verb:status` notifications back to the app when the verb is executed. The `id` property is a string value that is assigned by the app and is meaningful only to the app.
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/ack">Prev: ack</a>
|
||||
</p>
|
||||
10
markdown/docs/ws/jambonz-error.md
Normal file
10
markdown/docs/ws/jambonz-error.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# jambonz:error
|
||||
|
||||
A `jambonz:error` message is sent by jambonz to the websocket server if jambonz encounters some sort of fatal error (i.e. something that would necessitate ending the call unexpectedly) jambonz will send an error event to the far end app describing the problem.
|
||||
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/verb-status">Prev: verb:status</a>
|
||||
<a href="/docs/ws/ack">Next: ack</a>
|
||||
</p>
|
||||
46
markdown/docs/ws/overview.md
Normal file
46
markdown/docs/ws/overview.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Websocket API
|
||||
|
||||
The websocket API is functionally equivalent to the Webhook API. The reason we created this alternative API is that there are some use cases, primarily those involving a lot of asynchronous interaction with jambonz, that can be done much easier over a single websocket connection than over a combination of HTTP webhooks and REST APIs. As an example, some integrations with AI/bots have used the websocket API to good affect.
|
||||
|
||||
When you create a jambonz application in the jambonz portal and you want to use the websocket API, simply provide a ws(s) URL for the calling webhook instead of an http(s) URL. The call status webhook can be the same ws(s) URL. This will cause jambonz to establish a websocket connection to that URL when an incoming call (or outbound call) is routed to that application.
|
||||
|
||||
## Connection management
|
||||
|
||||
The websocket connection will be established by jambonz to the specified websocket url, The websocket subprotocol used shall be “ws.jambonz.org”. If jambonz fails to connect to the provided url, there will be no retry and the call shall be rejected.
|
||||
|
||||
Once connected, jambonz will send an initial JSON text message to the your server with the same parameters as are provided in the webhook call. The full message set is described below, but for now we can simply say that:
|
||||
- Only text frames are ever sent over the websocket connections; i.e. no binary frames.
|
||||
- The information content sent from jambonz to the your server is exactly the same content as that supplied webhooks.
|
||||
|
||||
The websocket should generally be closed only from the jambonz side, when a call is ended. If the your server closes the socket, jambonz will attempt to reconnect, up to a configurable number of reconnects. Upon reconnecting, jambonz will send an initial reconnect message containing only the callSid of the session. It is up to the your server to maintain any further context of the call between reconnections of the same call.
|
||||
|
||||
## Message format
|
||||
|
||||
As mentioned above, all messages will be JSON payloads sent as text frames. The following top-level properties will be commonly included:
|
||||
- *type*: all messages **must** have a type property.
|
||||
- Messages from jambonz to the your server will have the following types: [`session:new`, `session:reconnect`, `verb:hook`, `call:status`, `error`].
|
||||
- Messages from the your server to jambonz will have the following types: [`ack`, `command`].
|
||||
- *msgid*: every message sent from jambonz will include a unique message identifier. Messages from the your server application that are responses to jambonz messages (`ack`) **must** include the msgId that they are acknowledging.
|
||||
|
||||
Note that not all messages sent by jambonz need to be acknowledged. The message types which **must** be acknowledged are the `session:new`, and `verb:hook` messages. An app **may** choose to acknowledge other message types as well, but these acknowledgement messages will simply be discarded by jambonz.
|
||||
|
||||
## Message types
|
||||
In the sections that follow, we will describe each of the message types in detail. The table below provides summary information.
|
||||
|
||||
|message type|sent by|usage|
|
||||
|---|---|---|
|
||||
|session:new|jambonz|sent when a new call arrives (or an outbound call generated via the REST API has been answered). This is analogous to the initial webhook sent by jambonz to gather an initial set of instructions for the call.|
|
||||
|session:redirect|jambonz|sent when live call control has been used to retrieve a new application for either the parent or child call leg.|
|
||||
|session:reconnect|jambonz|sent when the websocket connection was closed unexpectedly by the websocket server and jambonz has successfully reconnected.|
|
||||
|call:status|jambonz|sent any time the call status changes.|
|
||||
|verb:hook|jambonz| sent when an action hook or event hook configured for a verb has been triggered (e.g. a “gather” verb has collected an utterance from the user).|
|
||||
|verb:status|jambonz|sent when a verb has just started or completed executing. See “command” below; this message is only sent if the app includes “id” properties on the verbs provided.|
|
||||
|jambonz:error|jambonz| if jambonz encounters some sort of fatal error (i.e. something that would necessitate ending the call unexpectedly) jambonz will send an error event to the far end app describing the problem.|
|
||||
|ack|websocket server|the ws server will respond to any `session:new` or `verb:hook` message with an `ack` message indicating that the provided content in the message has been processed. The ack message may optionally contain a payload of new instructions for jambonz.|
|
||||
|command|websocket server|the ws server will send this message when it wants to asynchronously provide a new set of instructions to jambonz. The app **may** include an `id` property in each of the verbs included in the command; if so, jambonz will send `verb:status` notifications back to the app when the verb is executed. The `id` property is a string value that is assigned by the app and is meaningful only to the app (i.e. to jambonz it is simply an opaque piece of tracking data).|
|
||||
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/session-new">Next: session:new</a>
|
||||
</p>
|
||||
77
markdown/docs/ws/session-new.md
Normal file
77
markdown/docs/ws/session-new.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# session:new
|
||||
|
||||
A `session:new` message is sent by jambonz to the websocket server when a new call arrives (or an outbound call generated via the REST API has been answered). This is analogous to the initial webhook sent by jambonz to gather an initial set of instructions for the call when using the HTTP-based webhook API.
|
||||
|
||||
The websocket server is responsible for replying with an [ack](/docs/ws/ack) message containing the the jambonz verbs to execute for this call.
|
||||
|
||||
|property|type|meaning|
|
||||
|--------|----|-------|
|
||||
|msgid|string|unique message identifier|
|
||||
|call_sid|string|unique call identifier|
|
||||
|b3|string|open telemetry span identifier (only if otel tracing is enabled|
|
||||
|data|object|JSON payload describing the call|
|
||||
|
||||
Here is an example `session:new` message.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "session:new",
|
||||
"msgid": "auuHioXGktYh2ZFYxf3hAA",
|
||||
"call_sid": "9fb35c28-9688-4531-943c-e280b04f3adf",
|
||||
"data": {
|
||||
"sip": {
|
||||
"headers": {
|
||||
"via": "SIP/2.0/UDP 3.212.205.202;rport=5060;branch=z9hG4bK3tv053jp1mcHQ;received=10.0.13.72",
|
||||
"max-forwards": "70",
|
||||
"from": "<sip:+15083084809@3.212.205.202:5060>;tag=9mgyBeaUy4H2S",
|
||||
"to": "<sip:+15083728299@3.212.205.202>",
|
||||
"call-id": "d8907723-0bc7-123b-09b5-12e962f3039b",
|
||||
"cseq": "48063641 INVITE",
|
||||
"contact": "<sip:10.0.13.72:5060>",
|
||||
"user-agent": "Twilio Gateway",
|
||||
"allow": "INVITE, ACK, CANCEL, BYE, REFER, NOTIFY, OPTIONS",
|
||||
"content-type": "application/sdp",
|
||||
"content-length": "281",
|
||||
"X-Account-Sid": "9351f46a-678c-43f5-b8a6-d4eb58d131af",
|
||||
"X-CID": "dae8845526bf7fe640ad0162238473e4@0.0.0.0",
|
||||
"X-Forwarded-For": "54.172.60.3",
|
||||
"X-Originating-Carrier": "Twilio",
|
||||
"X-Voip-Carrier-Sid": "c763b9dc-7113-450d-b86e-b3781d5fbec1",
|
||||
"X-Application-Sid": "7087fe50-8acb-4f3b-b820-97b573723aab",
|
||||
"Diversion": "<sip:+15083728299@twilio.com>;reason=unconditional",
|
||||
"X-Twilio-AccountSid": "AC58f23d38858ac262d6ee2e554b30c561",
|
||||
"X-Twilio-CallSid": "CAeea292c8a7c71dc67de46155ec667826",
|
||||
"p-asserted-identity": "<sip:+15083084809@206.147.76.45:5060>"
|
||||
},
|
||||
"raw": "INVITE sip:+15083728299@10.0.13.72:5070 SIP/2.0\r\nVia: SIP/2.0/UDP 3.212.205.202;rport=5060;branch=z9hG4bK3tv053jp1mcHQ;received=10.0.13.72\r\nMax-Forwards: 70\r\nFrom: <sip:+15083084809@3.212.205.202:5060>;tag=9mgyBeaUy4H2S\r\nTo: <sip:+15083728299@3.212.205.202>\r\nCall-ID: d8907723-0bc7-123b-09b5-12e962f3039b\r\nCSeq: 48063641 INVITE\r\nContact: <sip:10.0.13.72:5060>\r\nUser-Agent: Twilio Gateway\r\nAllow: INVITE, ACK, CANCEL, BYE, REFER, NOTIFY, OPTIONS\r\nContent-Type: application/sdp\r\nContent-Length: 281\r\nX-Account-Sid: 9351f46a-678c-43f5-b8a6-d4eb58d131af\r\nX-CID: dae8845526bf7fe640ad0162238473e4@0.0.0.0\r\nX-Forwarded-For: 54.172.60.3\r\nX-Originating-Carrier: Twilio\r\nX-Voip-Carrier-Sid: c763b9dc-7113-450d-b86e-b3781d5fbec1\r\nX-Application-Sid: 7087fe50-8acb-4f3b-b820-97b573723aab\r\nDiversion: <sip:+15083728299@twilio.com>;reason=unconditional\r\nX-Twilio-AccountSid: AC58f23d38858ac262d6ee2e554b30c561\r\nX-Twilio-CallSid: CAeea292c8a7c71dc67de46155ec667826\r\nP-Asserted-Identity: <sip:+15083084809@206.147.76.45:5060>\r\n\r\nv=0\r\no=root 81565042 81565042 IN IP4 10.0.13.72\r\ns=Twilio Media Gateway\r\nc=IN IP4 10.0.13.72\r\nt=0 0\r\nm=audio 40150 RTP/AVP 0 8 101\r\na=maxptime:20\r\na=rtpmap:0 PCMU/8000\r\na=rtpmap:8 PCMA/8000\r\na=rtpmap:101 telephone-event/8000\r\na=fmtp:101 0-16\r\na=sendrecv\r\na=rtcp:40151\r\na=ptime:20\r\n",
|
||||
"body": "v=0\r\no=root 81565042 81565042 IN IP4 10.0.13.72\r\ns=Twilio Media Gateway\r\nc=IN IP4 10.0.13.72\r\nt=0 0\r\nm=audio 40150 RTP/AVP 0 8 101\r\na=maxptime:20\r\na=rtpmap:0 PCMU/8000\r\na=rtpmap:8 PCMA/8000\r\na=rtpmap:101 telephone-event/8000\r\na=fmtp:101 0-16\r\na=sendrecv\r\na=rtcp:40151\r\na=ptime:20\r\n",
|
||||
"method": "INVITE",
|
||||
"version": "2.0",
|
||||
"uri": "sip:+15083728299@10.0.13.72:5070",
|
||||
"payload": [{
|
||||
"type": "application/sdp",
|
||||
"content": "v=0\r\no=root 81565042 81565042 IN IP4 10.0.13.72\r\ns=Twilio Media Gateway\r\nc=IN IP4 10.0.13.72\r\nt=0 0\r\nm=audio 40150 RTP/AVP 0 8 101\r\na=maxptime:20\r\na=rtpmap:0 PCMU/8000\r\na=rtpmap:8 PCMA/8000\r\na=rtpmap:101 telephone-event/8000\r\na=fmtp:101 0-16\r\na=sendrecv\r\na=rtcp:40151\r\na=ptime:20\r\n"
|
||||
}]
|
||||
},
|
||||
"direction": "inbound",
|
||||
"caller_name": "",
|
||||
"call_sid": "9fb35c28-9688-4531-943c-e280b04f3adf",
|
||||
"account_sid": "9351f46a-678c-43f5-b8a6-d4eb58d131af",
|
||||
"application_sid": "7087fe50-8acb-4f3b-b820-97b573723aab",
|
||||
"from": "+15083084809",
|
||||
"to": "+15083728299",
|
||||
"call_id": "d8907723-0bc7-123b-09b5-12e962f3039b",
|
||||
"sip_status": 100,
|
||||
"call_status": "trying",
|
||||
"originating_sip_ip": "54.172.60.3",
|
||||
"originating_sip_trunk_name": "Twilio",
|
||||
"local_sip_address": "10.0.13.72:5070"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/overview">Prev: overview</a>
|
||||
<a href="/docs/ws/session-redirect">Next: session:redirect</a>
|
||||
</p>
|
||||
9
markdown/docs/ws/session-reconnect.md
Normal file
9
markdown/docs/ws/session-reconnect.md
Normal file
@@ -0,0 +1,9 @@
|
||||
# session:reconnect
|
||||
|
||||
A `session:reconnect` message is sent by jambonz to the websocket server when the websocket connection was closed unexpectedly by the websocket server and jambonz has then successfully reconnected.
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/session-redirect">Prev: session:redirect</a>
|
||||
<a href="/docs/ws/call-status">Next: call:status</a>
|
||||
</p>
|
||||
13
markdown/docs/ws/session-redirect.md
Normal file
13
markdown/docs/ws/session-redirect.md
Normal file
@@ -0,0 +1,13 @@
|
||||
# session:redirect
|
||||
|
||||
A `session:redirect` message is sent when live call control has been used to retrieve a new application for either the parent or child call leg.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/session-new">Prev: session:new</a>
|
||||
<a href="/docs/ws/session-reconnect">Next: session:reconnect</a>
|
||||
</p>
|
||||
11
markdown/docs/ws/verb-hook.md
Normal file
11
markdown/docs/ws/verb-hook.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# verb:hook
|
||||
|
||||
A `verb:hook` message is sent by jambonz to the websocket server when an action hook or event hook configured for a verb has been triggered (e.g. a “gather” verb has collected an utterance from the user).
|
||||
|
||||
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/call-status">Prev: call:status</a>
|
||||
<a href="/docs/ws/verb-status">Next: verb:status</a>
|
||||
</p>
|
||||
11
markdown/docs/ws/verb-status.md
Normal file
11
markdown/docs/ws/verb-status.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# verb:status
|
||||
|
||||
A `verb:status` message is sent by jambonz to the websocket server when a verb has just started or completed executing.
|
||||
|
||||
> Note: `verb:status` messages are only sent when the app has provided an `id` property on verbs it includes in a `command` message.
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/ws/verb-hook">Prev: verb:hook</a>
|
||||
<a href="/docs/ws/jambonz-error">Next: jambonz:error</a>
|
||||
</p>
|
||||
Reference in New Issue
Block a user