diff --git a/data/docs.yml b/data/docs.yml
index 45c34cb..57a001d 100644
--- a/data/docs.yml
+++ b/data/docs.yml
@@ -57,6 +57,12 @@ navi:
-
path: say
title: say
+ -
+ path: sip-decline
+ title: sip:decline
+ -
+ path: sip-refer
+ title: sip:refer
-
path: tag
title: tag
diff --git a/markdown/docs/webhooks/listen.md b/markdown/docs/webhooks/listen.md
index 53520d5..71d3bd2 100644
--- a/markdown/docs/webhooks/listen.md
+++ b/markdown/docs/webhooks/listen.md
@@ -10,8 +10,6 @@ The listen verb can also be nested in a [dial](#dial) verb, which allows the aud
To utilize the listen verb, the customer must implement a websocket server to receive and process the audio. The endpoint should be prepared to accept websocket connections with a subprotocol name of 'audio.jambonz.org'.
-The listen verb includes a **url** property which is the url of the remote websocket server to send the audio to. The url may be an absolute or relative URL. HTTP Basic Authentication can optionally be used to protect the websocket endpoint by using the **wsAuth** property.
-
The format of the audio data sent over the websocket is 16-bit PCM encoding, with a user-specified sample rate. The audio is sent in binary frames over the websocket connection.
Additionally, one text frame is sent immediately after the websocket connection is established. This text frame contains a JSON string with all of the call attributes normally sent on an HTTP request (e.g. callSid, etc), plus **sampleRate** and **mixType** properties describing the audio sample rate and stream(s). Additional metadata can also be added to this payload using the **metadata** property as described in the table below. Once the intial text frame containing the metadata has been sent, the remote side should expect to receive only binary frames, containing audio. The remote side is not expected to send any data back over the websocket.
@@ -41,6 +39,41 @@ You can use the following options in the `listen` action:
| wsAuth.username | HTTP basic auth username to use on websocket connection | no |
| wsAuth.password | HTTP basic auth password to use on websocket connection | no |
+Bidirectional audio
+
+Audio can also be sent back over the websocket to jambonz. This audio, if supplied, will be played out to the caller. (Note: Bidirectional audio is not supported when the `listen` is nested in the context of a `dial` verb).
+
+The far-end websocket server supplies bidirectional audio by sending a JSON text frame over the websocket connection:
+```json
+{
+ "type": "playAudio",
+ "data": {
+ "audioContent": "base64-encoded content..",
+ "audioContentType": "raw",
+ "sampleRate": "16000"
+ }
+}
+```
+In the example above, raw (headerless) audio is sent. The audio must be 16-bit pcm encoded audio, with a configurable sample rate of either 8000, 16000, 24000, 32000, 48000, or 64000 khz. Alternatively, a wave file format can be supplied by using type "wav" (or "wave"), and in this case no `sampleRate` property is needed. In all cases, the audio must be base64 encoded when sent over the socket.
+
+Once a `playAudio` command has finished playing out the audio, a `playDone` json text frame will be sent over the websocket connection:
+```json
+{
+ "type": "playDone"
+}
+
+A `killAudio` command can also be sent by the websocket server to stop the playout of audio that was started via a previous `playAudio` command:
+```json
+{
+ "type": "killAudio"
+}
+
+And finally, if the websocket connection wishes to end the `listen`, it can send a `disconnect` command:
+```json
+{
+ "type": "disconnect"
+}
+
Prev: lex
Next: message
diff --git a/markdown/docs/webhooks/rasa.md b/markdown/docs/webhooks/rasa.md
index 78443ef..952533c 100644
--- a/markdown/docs/webhooks/rasa.md
+++ b/markdown/docs/webhooks/rasa.md
@@ -1,5 +1,5 @@
# rasa
-> New in v0.6.6
+> Added in v0.6.6
The `rasa` verb is used to connect a call to a [Rasa](https://rasa.com/) assistant.
```json
diff --git a/markdown/docs/webhooks/sip-decline.md b/markdown/docs/webhooks/sip-decline.md
index a9e0050..36778fa 100644
--- a/markdown/docs/webhooks/sip-decline.md
+++ b/markdown/docs/webhooks/sip-decline.md
@@ -27,5 +27,5 @@ You can use the following options in the `sip:decline` action:
Prev: say
-Next: tag
+Next: sip:refer
diff --git a/markdown/docs/webhooks/sip-refer.md b/markdown/docs/webhooks/sip-refer.md
new file mode 100644
index 0000000..eecb868
--- /dev/null
+++ b/markdown/docs/webhooks/sip-refer.md
@@ -0,0 +1,46 @@
+# sip:refer
+> Added in v0.6.7
+
+The sip:refer action is used to blind transfer a call. It will send a sip REFER to the far end carrier or sip phone, which must support the REFER in order for the transfer to work. After the sip:refer completes successfully, the call leg will have left the jambonz platform.
+
+```json
+{
+ "verb": "sip:refer",
+ "referTo": +15083084809,
+ "actionHook": "/action"
+}
+```
+
+You can use the following options in the `sip:refer` action:
+
+| option | description | required |
+| ------------- |-------------| -----|
+| referTo | a sip uri or a phone number / user identifier | yes |
+| referredBy | a sip uri or a phone number / user identifier; if not provided it will default to the identity of the party being transferred | no |
+| actionHook | a webhook to call when the transfer has completed | no |
+| eventHook | a webhook to call when NOTIFY messages of follow-on call status are received | no |
+| headers | additional SIP headers to include in the response | no
+
+The sip:refer verb completes when one of these conditions are met:
+- a failure response is received to the REFER
+- a 202 Accepted is received in response to the REFER, and a NOTIFY of the follow-on call status with a final call status is received.
+
+The sip:refer has an action hook that will provide details of the final result, as well as an event hook that is called for every NOTIFY received after a successful REFER.
+
+The *actionHook* webhook will contain the following additional parameters:
+
+- `referStatus`: the sip status response to the REFER request
+- `final_referred_call_status` - the final sip status of the subsequent call to the transferee. This is only provided in the case where the REFER is accepted and NOTIFY requests are received from the far end.
+
+The *eventHook* webhook will contain two parameters: `event` and `call_status`. The `event` parameter will always be `transfer-status` and the `call-status` will contain a sip status received in a NOTIFY after a successful REFER; e.g.
+```json
+{
+ "event": "transfer-status",
+ "call_status": "180"
+}
+```
+
+
+Prev: sip:decline
+Next: tag
+