# Gather DTMF from a call

Use this request to gather DTMF - digits entered by user. Gather command can be nested with a `playback` or a `say`.

## Gather DTMFs from call

> Gather DTMF from a channel call

```json
{"openapi":"3.0.3","info":{"title":"Channels","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Gather":{"type":"object","title":"Gather dtmfs from call","additionalProperties":false,"properties":{"maxNumKeys":{"type":"integer"},"endKey":{"$ref":"#/components/schemas/Key"},"timeout":{"type":"integer"},"retries":{"type":"integer"},"input":{"type":"string","enum":["dtmf","speech","dtmf speech"]},"speechLocale":{"type":"string","format":"locale-bcp47","default":"en-US","enum":["de-DE","en-AU","en-GB","en-US","es-US","it-IT","ja-JP","ko-KR","pt-BR","th-TH","zh-CN"]},"playback":{"$ref":"#/components/schemas/Play"},"say":{"$ref":"#/components/schemas/Say"}}},"Key":{"type":"string","enum":["0","1","2","3","4","5","6","7","8","9","*","#"]},"Play":{"type":"object","title":"Playback sound to Call","additionalProperties":false,"properties":{"media":{"type":"array","items":{"type":"string"},"maxItems":80,"nullable":true},"loop":{"type":"integer"},"timeout":{"type":"integer"},"pauseMilliseconds":{"type":"integer","minimum":0,"maximum":30000}},"required":["media"]},"Say":{"type":"object","title":"Say text to Call","additionalProperties":false,"properties":{"text":{"type":"string"},"locale":{"type":"string","format":"locale-bcp47","default":"en-US","enum":["arb","ar-AE","bg-BG","bn-IN","ca-ES","cs-CZ","cy-GB","cmn-CN","da-DK","de-CH","de-DE","de-AT","el-GR","en-AU","en-GB","en-IN","en-NZ","en-ZA","en-US","en-GB-WLS","es-ES","es-MX","es-US","eu-ES","fi-FI","fil-PH","fr-FR","fr-BE","fr-CA","gl-ES","gu-IN","he-IL","hi-IN","hu-HU","id-ID","is-IS","it-IT","ja-JP","ko-KR","lt-LT","lv-LV","ms-MY","nl-BE","nl-NL","nb-NO","pa-IN","pl-PL","pt-BR","pt-PT","ro-RO","ru-RU","sk-SK","sr-RS","sv-SE","ta-IN","te-IN","tr-TR","th-TH","uk-UA","vi-VN","yue-CN"]},"voice":{"type":"string"},"loop":{"type":"integer"},"timeout":{"type":"integer"}},"required":["text"]},"CallCommandResponse":{"type":"object","title":"CallCommandResponse","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Id-2"},"callId":{"$ref":"#/components/schemas/Id-2"},"callFlowId":{"nullable":true,"$ref":"#/components/schemas/Id-2"},"status":{"type":"string"},"command":{"type":"string"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/CallFlowCommandCondition"}}}},"Id-2":{"type":"string","format":"uuid"},"CallFlowCommandCondition":{"type":"object","title":"Conditions for command","additionalProperties":false,"properties":{"variable":{"type":"string","enum":["keys","speech"]},"operator":{"type":"string","enum":["eq","ne","==","!=","contains"]},"value":{"type":"string"}}},"RequestError":{"type":"object","properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n"},"message":{"type":"string","description":"A human-readable message that describes the error. An example is 'The requested resource does not exist: channel not found'.\n"}},"required":["code","message"]},"ValidationError":{"type":"object","properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n"},"message":{"type":"string","description":"A human-readable message that describes the error. An example is 'The requested resource does not exist: channel not found'.\n"},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["code","message"]}},"responses":{"requestError":{"description":"The request did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestError"}}}},"validationError":{"description":"The request did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/workspaces/{workspaceId}/channels/{channelId}/calls/{callId}/gather":{"post":{"summary":"Gather DTMFs from call","operationId":"gatherChannelCall","description":"Gather DTMF from a channel call","tags":["channel_call_command"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gather"}}}},"responses":{"202":{"description":"Call Command Gather was accepted for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallCommandResponse"}}}},"400":{"$ref":"#/components/responses/requestError"},"404":{"$ref":"#/components/responses/requestError"},"422":{"$ref":"#/components/responses/validationError"}}}}}}
```

{% tabs %}
{% tab title="Request Headers" %}

```
curl -X POST "https://api.bird.com/workspaces/{workspaceId}/channels/{channelId}/calls/{callId}/gather" \
     -H "Authorization: AccessKey YOUR_SECRET_TOKEN"
```

{% endtab %}

{% tab title="Request Body" %}

```
{​
  "maxNumKeys": 0,​
  "endKey": "0",​
  "timeout": 0,​
  "retries": 0,​
  "input": "dtmf",​
  "playback": {​
    "media": [​
      "string"​
    ],​
    "loop": 0,​
    "timeout": 0​
  },​
  "say": {​
    "text": "string",​
    "locale": [​
      "en-US"​
    ],​
    "voice": "male",​
    "loop": 0,​
    "timeout": 0​
  }​
​}
```

{% endtab %}

{% tab title="Response" %}

```
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "callId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "callFlowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "string",
  "command": "string"
}
```

{% endtab %}
{% endtabs %}