# Respond.io

> Manage your Respond.io inbox: create, update, tag and find contacts, send messages, assign and close conversations, and add internal comments.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/respond-io

## Actions

### Add comment to contact

Add an internal comment to a contact's conversation. Only your team sees it.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Comment (`text`, text, required): The comment, up to 1,000 characters.

**Outputs**

- `comment` (object): The comment

**Example output**

```json
{
  "comment": {
    "contactId": 123,
    "created_at": 1760000000,
    "text": "Called back"
  }
}
```

### Add tags to contact

Add up to 10 tags to a contact, creating any that are new.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Tags (`tags`, list, required): Up to 10 tag names. A tag that does not exist yet is created.

**Outputs**

- `contact` (text): The contact as addressed (id:, email: or phone:)
- `contact_id` (number): The contact's Respond.io id
- `tags` (list): The tags sent

**Example output**

```json
{
  "contact": "id:123",
  "contact_id": 123,
  "tags": [
    "vip"
  ]
}
```

### Assign conversation

Assign a contact's conversation to a user, or unassign it.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Assignee (`assignee`, text): The user to assign the conversation to. A user id or the user's email address can be typed or chained.
- Unassign (`unassign`, true/false): Remove the current assignee instead of choosing one.

**Outputs**

- `assignee` (number): The user id or email sent; empty when unassigned
- `contact` (text): The contact as addressed (id:, email: or phone:)
- `contact_id` (number): The contact's Respond.io id

**Example output**

```json
{
  "assignee": 7,
  "contact": "id:123",
  "contact_id": 123
}
```

### Create contact

Create a contact with an email address or phone number, then read it back so its id is available to later steps.

**Inputs**

- First name (`first_name`, text, required): The contact's first name.
- Email (`email`, text): The contact's email address.
- Phone (`phone`, text): The contact's phone number in international format, with + and the country code.
- Last name (`last_name`, text): The contact's last name.
- Language (`language`, text): A two-letter ISO 639-1 language code, like en or ms.
- Country (`country_code`, text): A two-letter ISO 3166-1 country code, like MY or US.
- Profile picture link (`profile_pic`, text): A public link to the contact's picture.
- Custom fields (`custom_fields`, object): Values by custom field name. Dates are YYYY-MM-DD, times HH:MM (24-hour), list values must match an option, and an empty value clears the field.

**Outputs**

- `contact` (object): The new contact
- `contact_id` (number): The contact's Respond.io id

**Example output**

```json
{
  "contact": {
    "assignee": {
      "email": "sam@example.com",
      "firstName": "Sam",
      "id": 7,
      "lastName": "Lee"
    },
    "countryCode": "MY",
    "created_at": 1760000000,
    "custom_fields": [
      {
        "name": "Plan",
        "value": "Pro"
      }
    ],
    "email": "jo@example.com",
    "firstName": "Jo",
    "id": 123,
    "isBlocked": false,
    "language": "en",
    "lastName": "Tan",
    "lifecycle": "New Lead",
    "phone": "+60121233112",
    "profilePic": null,
    "status": "open",
    "tags": [
      "vip"
    ]
  },
  "contact_id": 123
}
```

### Create or update contact

Update the contact matching an id, email or phone, or create one when none matches. Returns the contact's id.

**Inputs**

- First name (`first_name`, text, required): The contact's first name.
- Contact to match (`contact`, text): The id, email or phone of the contact to update. Leave empty to match on the email or phone below; a new contact is created when none match.
- Email (`email`, text): The contact's email address.
- Phone (`phone`, text): The contact's phone number in international format, with + and the country code.
- Last name (`last_name`, text): The contact's last name.
- Language (`language`, text): A two-letter ISO 639-1 language code, like en or ms.
- Country (`country_code`, text): A two-letter ISO 3166-1 country code, like MY or US.
- Profile picture link (`profile_pic`, text): A public link to the contact's picture.
- Custom fields (`custom_fields`, object): Values by custom field name. Dates are YYYY-MM-DD, times HH:MM (24-hour), list values must match an option, and an empty value clears the field.

**Outputs**

- `contact` (text): The contact as addressed (id:, email: or phone:)
- `contact_id` (number): The contact's Respond.io id

**Example output**

```json
{
  "contact": "email:jo@example.com",
  "contact_id": 123
}
```

### Create tag

Create a workspace tag with a description, colour and emoji.

**Inputs**

- Tag name (`name`, text, required): The tag's name. Tags are addressed by name.
- Description (`description`, text): What the tag is for.
- Colour (`color`, text): The tag's colour. One of: `tag-grey` (Grey), `tag-red` (Red), `tag-orange` (Orange), `tag-yellow` (Yellow), `tag-green` (Green), `tag-blue` (Blue), `tag-indigo` (Indigo), `tag-purple` (Purple).
- Emoji (`emoji`, text): An emoji shown with the tag.

**Outputs**

- `tag` (object): The tag

**Example output**

```json
{
  "tag": {
    "colorCode": "tag-yellow",
    "description": "Top customers",
    "emoji": "\u2b50",
    "id": 11,
    "name": "vip"
  }
}
```

### Delete contact

Delete a contact and its conversation history.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.

**Outputs**

- `contact` (text): The contact as addressed (id:, email: or phone:)
- `contact_id` (number): The contact's Respond.io id
- `deleted` (true/false): Always true

**Example output**

```json
{
  "contact": "id:123",
  "contact_id": 123,
  "deleted": true
}
```

### Delete tag

Delete a workspace tag by name, taking it off every contact.

**Inputs**

- Tag name (`name`, text, required): The tag's name. Tags are addressed by name.

**Outputs**

- `deleted` (true/false): Always true
- `message` (text): Respond.io's reply
- `name` (text): The tag deleted

**Example output**

```json
{
  "deleted": true,
  "message": "Tag deleted successfully",
  "name": "vip"
}
```

### Get contact

Get a contact by id, email or phone: name, details, custom fields, tags, lifecycle stage, assignee and conversation status.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.

**Outputs**

- `contact` (object): The contact

**Example output**

```json
{
  "contact": {
    "assignee": {
      "email": "sam@example.com",
      "firstName": "Sam",
      "id": 7,
      "lastName": "Lee"
    },
    "countryCode": "MY",
    "created_at": 1760000000,
    "custom_fields": [
      {
        "name": "Plan",
        "value": "Pro"
      }
    ],
    "email": "jo@example.com",
    "firstName": "Jo",
    "id": 123,
    "isBlocked": false,
    "language": "en",
    "lastName": "Tan",
    "lifecycle": "New Lead",
    "phone": "+60121233112",
    "profilePic": null,
    "status": "open",
    "tags": [
      "vip"
    ]
  }
}
```

### Get message

Get one message in a contact's conversation, with its content, direction, sender and delivery status history.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Message ID (`message_id`, text, required): The message's id, from 'Send message' or 'List messages'.

**Outputs**

- `message` (object): The message

**Example output**

```json
{
  "message": {
    "channelId": 9,
    "channelMessageId": "abc",
    "contactId": 123,
    "message": {
      "text": "Hello",
      "type": "text"
    },
    "messageId": 456,
    "sender": {
      "source": "api"
    },
    "status": [
      {
        "timestamp": 1760000000,
        "value": "sent"
      }
    ],
    "traffic": "outgoing"
  }
}
```

### List channels

List the messaging channels connected to the workspace.

**Inputs**

- Page size (`limit`, number): How many to return, 1 to 100. Respond.io's default is 10. From 1 to 100.
- Next page cursor (`cursor_id`, text): To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

**Outputs**

- `channels` (list): The channels
- `count` (number): How many on this page
- `next_cursor_id` (text): Pass as 'Next page cursor' for the next page; empty on the last page

**Example output**

```json
{
  "channels": [
    {
      "created_at": 1750000000,
      "id": 9,
      "name": "Support bot",
      "source": "telegram"
    }
  ],
  "count": 1,
  "next_cursor_id": null
}
```

### List contact channels

List the channels a contact is reachable on, with when they last messaged on each.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Page size (`limit`, number): How many to return, 1 to 100. Respond.io's default is 10. From 1 to 100.
- Next page cursor (`cursor_id`, text): To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

**Outputs**

- `channels` (list): The channels
- `count` (number): How many on this page
- `next_cursor_id` (text): Pass as 'Next page cursor' for the next page; empty on the last page

**Example output**

```json
{
  "channels": [
    {
      "created_at": 1750000000,
      "id": 9,
      "lastIncomingMessageTime": 1760000000,
      "lastMessageTime": 1760000000,
      "meta": {},
      "name": "Support bot",
      "source": "telegram"
    }
  ],
  "count": 1,
  "next_cursor_id": null
}
```

### List contacts

List or search contacts by name, email or phone, optionally only those with any of some tags, at a lifecycle stage or assigned to a user. One page at a time.

**Inputs**

- Search (`search`, text): Text to match against name, email or phone.
- Has any of these tags (`tags`, list): Only contacts with at least one of these tags.
- Lifecycle stage (`lifecycle`, text): Only contacts at this lifecycle stage.
- Assigned to (`assignee`, text): Only contacts assigned to this user.
- Page size (`limit`, number): How many to return, 1 to 100. Respond.io's default is 10. From 1 to 100.
- Next page cursor (`cursor_id`, text): To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

**Outputs**

- `contacts` (list): The contacts
- `count` (number): How many on this page
- `next_cursor_id` (text): Pass as 'Next page cursor' for the next page; empty on the last page

**Example output**

```json
{
  "contacts": [
    {
      "assignee": {
        "email": "sam@example.com",
        "firstName": "Sam",
        "id": 7,
        "lastName": "Lee"
      },
      "countryCode": "MY",
      "created_at": 1760000000,
      "custom_fields": [
        {
          "name": "Plan",
          "value": "Pro"
        }
      ],
      "email": "jo@example.com",
      "firstName": "Jo",
      "id": 123,
      "isBlocked": false,
      "language": "en",
      "lastName": "Tan",
      "lifecycle": "New Lead",
      "phone": "+60121233112",
      "profilePic": null,
      "status": "open",
      "tags": [
        "vip"
      ]
    }
  ],
  "count": 1,
  "next_cursor_id": null
}
```

### List messages

List the messages in a contact's conversation, newest first.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Page size (`limit`, number): How many messages to return, 1 to 50. The default is 10. From 1 to 50.
- Next page cursor (`cursor_id`, text): To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

**Outputs**

- `count` (number): How many on this page
- `messages` (list): The messages
- `next_cursor_id` (text): Pass as 'Next page cursor' for the next page; empty on the last page

**Example output**

```json
{
  "count": 1,
  "messages": [
    {
      "channelId": 9,
      "channelMessageId": "abc",
      "contactId": 123,
      "message": {
        "text": "Hello",
        "type": "text"
      },
      "messageId": 456,
      "sender": {
        "source": "api"
      },
      "status": [
        {
          "timestamp": 1760000000,
          "value": "sent"
        }
      ],
      "traffic": "outgoing"
    }
  ],
  "next_cursor_id": null
}
```

### List users

List the workspace's users with their role and team. Invited users who have not accepted yet are not included.

**Inputs**

- Page size (`limit`, number): How many to return, 1 to 100. Respond.io's default is 10. From 1 to 100.
- Next page cursor (`cursor_id`, text): To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

**Outputs**

- `count` (number): How many on this page
- `next_cursor_id` (text): Pass as 'Next page cursor' for the next page; empty on the last page
- `users` (list): The users

**Example output**

```json
{
  "count": 1,
  "next_cursor_id": null,
  "users": [
    {
      "email": "sam@example.com",
      "firstName": "Sam",
      "id": 7,
      "lastName": "Lee",
      "restrictions": [],
      "role": "manager",
      "team": null
    }
  ]
}
```

### Open or close conversation

Open a contact's conversation, or close it with an optional closing note and summary.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Status (`status`, text, required): Open or close the contact's conversation. One of: `open`, `close` (Closed).
- Closing note (`closing_note`, text): When closing, the closing note category to file it under.
- Summary (`summary`, text): When closing with a closing note, a summary (up to 512 characters).

**Outputs**

- `contact` (text): The contact as addressed (id:, email: or phone:)
- `contact_id` (number): The contact's Respond.io id
- `status` (text): open or close

**Example output**

```json
{
  "contact": "id:123",
  "contact_id": 123,
  "status": "close"
}
```

### Remove tags from contact

Take up to 10 tags off a contact.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Tags (`tags`, list, required): Up to 10 tag names. A tag that does not exist yet is created.

**Outputs**

- `contact` (text): The contact as addressed (id:, email: or phone:)
- `contact_id` (number): The contact's Respond.io id
- `tags` (list): The tags sent

**Example output**

```json
{
  "contact": "id:123",
  "contact_id": 123,
  "tags": [
    "vip"
  ]
}
```

### Send message

Send a contact a text, an attachment or an email on a chosen channel, or on the channel they last used.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Message type (`message_type`, text): What to send. Email needs an email channel. One of: `text`, `attachment` (Attachment (image, video, audio or file)), `email`. Default: `text`.
- Text (`text`, text): The message, or the email's body. Variables like {{$contact.name}} are filled in by Respond.io.
- Channel (`channel_id`, text): The channel to send on. Leave empty for the channel the contact last used, which fails for a contact who has never messaged you.
- Message tag (Facebook and Instagram) (`message_tag`, text): Needed only for a Facebook or Instagram text sent more than 24 hours after the contact last wrote. One of: `ACCOUNT_UPDATE` (Account update), `POST_PURCHASE_UPDATE` (Post-purchase update), `CONFIRMED_EVENT_UPDATE` (Confirmed event update).
- Attachment type (`attachment_type`, text): What the attachment is. The default is file. One of: `image`, `video`, `audio`, `file`.
- Attachment link (`attachment_url`, text): A public link to the file to attach. Required for an attachment message; optional for an email.
- Attachment file name (`file_name`, text): For an email, the attachment's file name. Taken from the link if empty.
- Email subject (`subject`, text): For an email, its subject.
- Email CC (`cc`, list): For an email, addresses to copy.
- Email BCC (`bcc`, list): For an email, addresses to blind-copy.

**Outputs**

- `channel_id` (number): The channel chosen; empty for the last used
- `contact` (text): The contact as addressed (id:, email: or phone:)
- `message_id` (number): The message's id

**Example output**

```json
{
  "channel_id": 9,
  "contact": "id:123",
  "message_id": 456
}
```

### Update contact

Change a contact's name, email, phone, language, country, picture or custom fields. Only the fields given change.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- First name (`first_name`, text): The contact's first name.
- Email (`email`, text): The contact's email address.
- Phone (`phone`, text): The contact's phone number in international format, with + and the country code.
- Last name (`last_name`, text): The contact's last name.
- Language (`language`, text): A two-letter ISO 639-1 language code, like en or ms.
- Country (`country_code`, text): A two-letter ISO 3166-1 country code, like MY or US.
- Profile picture link (`profile_pic`, text): A public link to the contact's picture.
- Custom fields (`custom_fields`, object): Values by custom field name. Dates are YYYY-MM-DD, times HH:MM (24-hour), list values must match an option, and an empty value clears the field.

**Outputs**

- `contact` (text): The contact as addressed (id:, email: or phone:)
- `contact_id` (number): The contact's Respond.io id
- `updated_fields` (list): The fields sent

**Example output**

```json
{
  "contact": "id:123",
  "contact_id": 123,
  "updated_fields": [
    "lastName"
  ]
}
```

### Update contact lifecycle stage

Move a contact to a lifecycle stage, or clear its stage.

**Inputs**

- Contact (`contact`, text, required): The contact's id, email address, or phone number in international format (+ and country code). A link to the contact on app.respond.io works too.
- Lifecycle stage (`stage`, text): The stage's name exactly as in Respond.io's lifecycle settings, like New Lead.
- Clear stage (`clear`, true/false): Remove the contact's lifecycle stage instead.

**Outputs**

- `contact` (text): The contact as addressed (id:, email: or phone:)
- `lifecycle` (text): The stage set; empty when cleared
- `message` (text): Respond.io's reply

**Example output**

```json
{
  "contact": "id:123",
  "lifecycle": "New Lead",
  "message": "Contact lifecycle stage updated successfully!"
}
```