---
title: "Human Contacts"
description: "Generic agent-to-human outreach for help, questions, or feedback"
---

## Create Human Contact

<ParamField path="POST /humanlayer/v1/human_contacts" method="POST">
  Create a human contact
</ParamField>

### Request Body

<ParamField body="human_contact" type="object">
  <Expandable title="HumanContact">
    <ParamField body="run_id" type="string" required>
      Unique identifier for the execution run
    </ParamField>
    <ParamField body="call_id" type="string" required>
      Unique identifier for this specific function call
    </ParamField>
    <ParamField body="spec" type="object" required>
      <Expandable title="HumanContactSpec">
        <ParamField body="msg" type="string" required>
          Message to send to the human
        </ParamField>
        <ParamField body="channel" type="object">
          Optional communication channel configuration
          <Expandable title="ContactChannel">
            <ParamField body="slack" type="object">
              <Expandable title="SlackContactChannel">
                <ParamField body="channel_or_user_id" type="string" required>
                  Slack channel or user ID (e.g. C123456 or U123456)
                </ParamField>
                <ParamField body="context_about_channel_or_user" type="string">
                  Optional context about the channel/user for the LLM
                </ParamField>
                <ParamField body="bot_token" type="string">
                  Optional custom Slack bot token
                </ParamField>
                <ParamField body="experimental_slack_blocks" type="boolean">
                  Optional flag for experimental Slack blocks
                </ParamField>
              </Expandable>
            </ParamField>
            <ParamField body="sms" type="object">
              <Expandable title="SMSContactChannel">
                <ParamField body="phone_number" type="string" required>
                  Phone number to send SMS to
                </ParamField>
                <ParamField body="context_about_user" type="string">
                  Optional context about the user for the LLM
                </ParamField>
              </Expandable>
            </ParamField>
            <ParamField body="whatsapp" type="object">
              <Expandable title="WhatsAppContactChannel">
                <ParamField body="phone_number" type="string" required>
                  Phone number for WhatsApp
                </ParamField>
                <ParamField body="context_about_user" type="string">
                  Optional context about the user for the LLM
                </ParamField>
              </Expandable>
            </ParamField>
            <ParamField body="email" type="object">
              <Expandable title="EmailContactChannel">
                <ParamField body="address" type="string" required>
                  Email address
                </ParamField>
                <ParamField body="context_about_user" type="string">
                  Optional context about the user for the LLM
                </ParamField>
                <ParamField body="experimental_subject_line" type="string">
                  Optional custom email subject line
                </ParamField>
                <ParamField
                  body="experimental_references_message_id"
                  type="string"
                >
                  Optional References message ID
                </ParamField>
                <ParamField
                  body="experimental_in_reply_to_message_id"
                  type="string"
                >
                  Optional In-Reply-To message ID
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
        <ParamField body="response_options" type="array">
          Optional list of rejection reason options
          <Expandable title="ResponseOption">
            <ParamField body="name" type="string" required>
              Name of the response option
            </ParamField>
            <ParamField body="title" type="string">
              Optional display title
            </ParamField>
            <ParamField body="description" type="string">
              Optional description
            </ParamField>
            <ParamField body="prompt_fill" type="string">
              Optional prompt fill text
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ParamField body="human_contact" type="object">
  <Expandable title="HumanContact">
    <ParamField body="run_id" type="string" required>
      Unique identifier for the execution run
    </ParamField>
    <ParamField body="call_id" type="string" required>
      Unique identifier for this specific function call
    </ParamField>
    <ParamField body="spec" type="object" required>
      <Expandable title="HumanContactSpec">
        <ParamField body="msg" type="string" required>
          Message to send to the human
        </ParamField>
        <ParamField body="channel" type="object">
          Optional communication channel configuration
          <Expandable title="ContactChannel">
            <ParamField body="slack" type="object">
              <Expandable title="SlackContactChannel">
                <ParamField body="channel_or_user_id" type="string" required>
                  Slack channel or user ID (e.g. C123456 or U123456)
                </ParamField>
                <ParamField body="context_about_channel_or_user" type="string">
                  Optional context about the channel/user for the LLM
                </ParamField>
                <ParamField body="bot_token" type="string">
                  Optional custom Slack bot token
                </ParamField>
                <ParamField body="experimental_slack_blocks" type="boolean">
                  Optional flag for experimental Slack blocks
                </ParamField>
              </Expandable>
            </ParamField>
            <ParamField body="sms" type="object">
              <Expandable title="SMSContactChannel">
                <ParamField body="phone_number" type="string" required>
                  Phone number to send SMS to
                </ParamField>
                <ParamField body="context_about_user" type="string">
                  Optional context about the user for the LLM
                </ParamField>
              </Expandable>
            </ParamField>
            <ParamField body="whatsapp" type="object">
              <Expandable title="WhatsAppContactChannel">
                <ParamField body="phone_number" type="string" required>
                  Phone number for WhatsApp
                </ParamField>
                <ParamField body="context_about_user" type="string">
                  Optional context about the user for the LLM
                </ParamField>
              </Expandable>
            </ParamField>
            <ParamField body="email" type="object">
              <Expandable title="EmailContactChannel">
                <ParamField body="address" type="string" required>
                  Email address
                </ParamField>
                <ParamField body="context_about_user" type="string">
                  Optional context about the user for the LLM
                </ParamField>
                <ParamField body="experimental_subject_line" type="string">
                  Optional custom email subject line
                </ParamField>
                <ParamField
                  body="experimental_references_message_id"
                  type="string"
                >
                  Optional References message ID
                </ParamField>
                <ParamField
                  body="experimental_in_reply_to_message_id"
                  type="string"
                >
                  Optional In-Reply-To message ID
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
        <ParamField body="response_options" type="array">
          Optional list of response options
          <Expandable title="ResponseOption">
            <ParamField body="name" type="string" required>
              Name of the response option
            </ParamField>
            <ParamField body="title" type="string">
              Optional display title
            </ParamField>
            <ParamField body="description" type="string">
              Optional description
            </ParamField>
            <ParamField body="prompt_fill" type="string">
              Optional prompt fill text
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Example Request

```json
{
  "run_id": "run_123",
  "call_id": "call_456",
  "spec": {
    "msg": "Hello, I tried to restart pod core-api-249832490-aj37ux but its stuck in an ImagePullBackOff state. Can you help?",
    "channel": {
      "slack": {
        "channel_or_user_id": "C123456",
        "context_about_channel_or_user": "A channel w/ the SRE team"
      }
    }
  }
}
```

or, for email, you can use an [email contact channel](/channels/email)

````json
{
  "run_id": "run_123",
  "call_id": "call_456",
  "spec": {
    "msg": "Hi, I need help reviewing this PR. Can you take a look when you have a chance?",
    "subject": "PR Review Request",
    "channel": {
      "email": {
        "address": "engineering@company.com",
        "subject": "PR Review Request",
        "in_reply_to": "msg_789"
      }
    }
  }
}


Or, in ruby:

```ruby
require 'net/http'
require 'json'

uri = URI('https://api.humanlayer.io/humanlayer/v1/human_contacts')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path,
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer YOUR_API_KEY'
)

request.body = {
  run_id: 'run_123',
  call_id: 'call_456',
  spec: {
    msg: 'Hi, I need help reviewing this PR. Can you take a look when you have a chance?',
    subject: 'PR Review Request',
    channel: {
      email: {
        address: 'engineering@company.com',
        subject: 'PR Review Request',
        in_reply_to: 'msg_789'
      }
    }
  }
}.to_json

response = http.request(request)
puts response.body

````

or with curl

```
curl -X POST https://api.humanlayer.io/humanlayer/v1/human_contacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"run_id": "run_123", "call_id": "call_456", "spec": {"msg": "Hi, I need help reviewing this PR. Can you take a look when you have a chance?"}}'
```
