Respond.io

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

Actions

Action	What it does
Add comment to contact	Add an internal comment to a contact's conversation.
Add tags to contact	Add up to 10 tags to a contact, creating any that are new.
Assign conversation	Assign a contact's conversation to a user, or unassign it.
Create contact	Create a contact with an email address or phone number, then read it back so its id is available to later steps.
Create or update contact	Update the contact matching an id, email or phone, or create one when none matches.
Create tag	Create a workspace tag with a description, colour and emoji.
Delete contact	Delete a contact and its conversation history.
Delete tag	Delete a workspace tag by name, taking it off every contact.
Get contact	Get a contact by id, email or phone: name, details, custom fields, tags, lifecycle stage, assignee and conversation status.
Get message	Get one message in a contact's conversation, with its content, direction, sender and delivery status history.
List channels	List the messaging channels connected to the workspace.
List contact channels	List the channels a contact is reachable on, with when they last messaged on each.
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.
List messages	List the messages in a contact's conversation, newest first.
List users	List the workspace's users with their role and team.
Open or close conversation	Open a contact's conversation, or close it with an optional closing note and summary.
Remove tags from contact	Take up to 10 tags off a contact.
Send message	Send a contact a text, an attachment or an email on a chosen channel, or on the channel they last used.
Update contact	Change a contact's name, email, phone, language, country, picture or custom fields.
Update contact lifecycle stage	Move a contact to a lifecycle stage, or clear its stage.

Add comment to contact

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

Inputs

ContactcontacttextRequired: 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.
CommenttexttextRequired: The comment, up to 1,000 characters.

Outputs

commentobject: The comment

Example output

{
  "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

ContactcontacttextRequired: 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.
TagstagslistRequired: Up to 10 tag names. A tag that does not exist yet is created.

Outputs

contacttext: The contact as addressed (id:, email: or phone:)
contact_idnumber: The contact's Respond.io id
tagslist: The tags sent

Example output

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

Assign conversation

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

Inputs

ContactcontacttextRequired: 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.
Assigneeassigneetext: The user to assign the conversation to. A user id or the user's email address can be typed or chained.
Unassignunassigntrue/false: Remove the current assignee instead of choosing one.

Outputs

assigneenumber: The user id or email sent; empty when unassigned
contacttext: The contact as addressed (id:, email: or phone:)
contact_idnumber: The contact's Respond.io id

Example output

{
  "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 namefirst_nametextRequired: The contact's first name.
Emailemailtext: The contact's email address.
Phonephonetext: The contact's phone number in international format, with + and the country code.
Last namelast_nametext: The contact's last name.
Languagelanguagetext: A two-letter ISO 639-1 language code, like en or ms.
Countrycountry_codetext: A two-letter ISO 3166-1 country code, like MY or US.
Profile picture linkprofile_pictext: A public link to the contact's picture.
Custom fieldscustom_fieldsobject: 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

contactobject: The new contact
contact_idnumber: The contact's Respond.io id

Example output

{
  "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 namefirst_nametextRequired: The contact's first name.
Contact to matchcontacttext: 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.
Emailemailtext: The contact's email address.
Phonephonetext: The contact's phone number in international format, with + and the country code.
Last namelast_nametext: The contact's last name.
Languagelanguagetext: A two-letter ISO 639-1 language code, like en or ms.
Countrycountry_codetext: A two-letter ISO 3166-1 country code, like MY or US.
Profile picture linkprofile_pictext: A public link to the contact's picture.
Custom fieldscustom_fieldsobject: 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

contacttext: The contact as addressed (id:, email: or phone:)
contact_idnumber: The contact's Respond.io id

Example output

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

Create tag

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

Inputs

Tag namenametextRequired: The tag's name. Tags are addressed by name.
Descriptiondescriptiontext: What the tag is for.
Colourcolortext: 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).
Emojiemojitext: An emoji shown with the tag.

Outputs

tagobject: The tag

Example output

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

Delete contact

Delete a contact and its conversation history.

Inputs

ContactcontacttextRequired: 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

contacttext: The contact as addressed (id:, email: or phone:)
contact_idnumber: The contact's Respond.io id
deletedtrue/false: Always true

Example output

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

Delete tag

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

Inputs

Tag namenametextRequired: The tag's name. Tags are addressed by name.

Outputs

deletedtrue/false: Always true
messagetext: Respond.io's reply
nametext: The tag deleted

Example output

{
  "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

ContactcontacttextRequired: 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

contactobject: The contact

Example output

{
  "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

ContactcontacttextRequired: 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 IDmessage_idtextRequired: The message's id, from 'Send message' or 'List messages'.

Outputs

messageobject: The message

Example output

{
  "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 sizelimitnumber: How many to return, 1 to 100. Respond.io's default is 10.From 1 to 100.
Next page cursorcursor_idtext: To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

Outputs

channelslist: The channels
countnumber: How many on this page
next_cursor_idtext: Pass as 'Next page cursor' for the next page; empty on the last page

Example output

{
  "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

ContactcontacttextRequired: 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 sizelimitnumber: How many to return, 1 to 100. Respond.io's default is 10.From 1 to 100.
Next page cursorcursor_idtext: To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

Outputs

channelslist: The channels
countnumber: How many on this page
next_cursor_idtext: Pass as 'Next page cursor' for the next page; empty on the last page

Example output

{
  "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

Searchsearchtext: Text to match against name, email or phone.
Has any of these tagstagslist: Only contacts with at least one of these tags.
Lifecycle stagelifecycletext: Only contacts at this lifecycle stage.
Assigned toassigneetext: Only contacts assigned to this user.
Page sizelimitnumber: How many to return, 1 to 100. Respond.io's default is 10.From 1 to 100.
Next page cursorcursor_idtext: To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

Outputs

contactslist: The contacts
countnumber: How many on this page
next_cursor_idtext: Pass as 'Next page cursor' for the next page; empty on the last page

Example output

{
  "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

ContactcontacttextRequired: 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 sizelimitnumber: How many messages to return, 1 to 50. The default is 10.From 1 to 50.
Next page cursorcursor_idtext: To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

Outputs

countnumber: How many on this page
messageslist: The messages
next_cursor_idtext: Pass as 'Next page cursor' for the next page; empty on the last page

Example output

{
  "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 sizelimitnumber: How many to return, 1 to 100. Respond.io's default is 10.From 1 to 100.
Next page cursorcursor_idtext: To get the next page, the next_cursor_id an earlier run of this list returned. Leave empty for the first page.

Outputs

countnumber: How many on this page
next_cursor_idtext: Pass as 'Next page cursor' for the next page; empty on the last page
userslist: The users

Example output

{
  "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

ContactcontacttextRequired: 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.
StatusstatustextRequired: Open or close the contact's conversation.One of: open, close (Closed).
Closing noteclosing_notetext: When closing, the closing note category to file it under.
Summarysummarytext: When closing with a closing note, a summary (up to 512 characters).

Outputs

contacttext: The contact as addressed (id:, email: or phone:)
contact_idnumber: The contact's Respond.io id
statustext: open or close

Example output

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

Remove tags from contact

Take up to 10 tags off a contact.

Inputs

ContactcontacttextRequired: 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.
TagstagslistRequired: Up to 10 tag names. A tag that does not exist yet is created.

Outputs

contacttext: The contact as addressed (id:, email: or phone:)
contact_idnumber: The contact's Respond.io id
tagslist: The tags sent

Example output

{
  "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

ContactcontacttextRequired: 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 typemessage_typetext: What to send. Email needs an email channel.One of: text, attachment (Attachment (image, video, audio or file)), email. Default: text.
Texttexttext: The message, or the email's body. Variables like {{$contact.name}} are filled in by Respond.io.
Channelchannel_idtext: 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_tagtext: 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 typeattachment_typetext: What the attachment is. The default is file.One of: image, video, audio, file.
Attachment linkattachment_urltext: A public link to the file to attach. Required for an attachment message; optional for an email.
Attachment file namefile_nametext: For an email, the attachment's file name. Taken from the link if empty.
Email subjectsubjecttext: For an email, its subject.
Email CCcclist: For an email, addresses to copy.
Email BCCbcclist: For an email, addresses to blind-copy.

Outputs

channel_idnumber: The channel chosen; empty for the last used
contacttext: The contact as addressed (id:, email: or phone:)
message_idnumber: The message's id

Example output

{
  "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

ContactcontacttextRequired: 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 namefirst_nametext: The contact's first name.
Emailemailtext: The contact's email address.
Phonephonetext: The contact's phone number in international format, with + and the country code.
Last namelast_nametext: The contact's last name.
Languagelanguagetext: A two-letter ISO 639-1 language code, like en or ms.
Countrycountry_codetext: A two-letter ISO 3166-1 country code, like MY or US.
Profile picture linkprofile_pictext: A public link to the contact's picture.
Custom fieldscustom_fieldsobject: 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

contacttext: The contact as addressed (id:, email: or phone:)
contact_idnumber: The contact's Respond.io id
updated_fieldslist: The fields sent

Example output

{
  "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

ContactcontacttextRequired: 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 stagestagetext: The stage's name exactly as in Respond.io's lifecycle settings, like New Lead.
Clear stagecleartrue/false: Remove the contact's lifecycle stage instead.

Outputs

contacttext: The contact as addressed (id:, email: or phone:)
lifecycletext: The stage set; empty when cleared
messagetext: Respond.io's reply

Example output

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

ActionsCopy Anchor Link

Add comment to contactCopy Anchor Link

Inputs

Outputs

Add tags to contactCopy Anchor Link

Inputs

Outputs

Assign conversationCopy Anchor Link

Inputs

Outputs

Create contactCopy Anchor Link

Inputs

Outputs

Create or update contactCopy Anchor Link

Inputs

Outputs

Create tagCopy Anchor Link

Inputs

Outputs

Delete contactCopy Anchor Link

Inputs

Outputs

Delete tagCopy Anchor Link

Inputs

Outputs

Get contactCopy Anchor Link

Inputs

Outputs

Get messageCopy Anchor Link

Inputs

Outputs

List channelsCopy Anchor Link

Inputs

Outputs

List contact channelsCopy Anchor Link

Inputs

Outputs

List contactsCopy Anchor Link

Inputs

Outputs

List messagesCopy Anchor Link

Inputs

Outputs

List usersCopy Anchor Link

Inputs

Outputs

Open or close conversationCopy Anchor Link

Inputs

Outputs

Remove tags from contactCopy Anchor Link

Inputs

Outputs

Send messageCopy Anchor Link

Inputs

Outputs

Update contactCopy Anchor Link

Inputs

Outputs

Update contact lifecycle stageCopy Anchor Link

Inputs

Outputs

On this page

Actions

Add comment to contact

Add tags to contact

Assign conversation

Create contact

Create or update contact

Create tag

Delete contact

Delete tag

Get contact

Get message

List channels

List contact channels

List contacts

List messages

List users

Open or close conversation

Remove tags from contact

Send message

Update contact

Update contact lifecycle stage