[yasser-aboelgheit-intercom]

Why?

Creating a conversation finds the contact by any one of from.id, from.user_id or from.email, but the spec required id and didn't list the other two.

How?

Lists all three identifiers with only type required, in 2.17 and Preview. In the Preview SDK, from.id becomes optional and from.user_id and from.email are added.

_{Generated with Claude Code}

[cathalging]

One wording fix. user_id only matches contacts with the user role, so type: lead with a user_id returns a 404. With type: lead, email matches leads, and fails with multiple_users if several leads share it. Suggested for 2.17 and Preview:

user_id:
  description: The external identifier you gave the user. Matches users only; for a lead, use `id` or `email`.
email:
  description: The contact's email. Matches a user or a lead, depending on `type`. If several leads share the email, the request fails with `multiple_users`; use `id` instead.

@yasser-aboelgheit-intercom, your call: fix this here, or approve as-is and take the wording as a follow-up?

~ Automated via Claude (about: https://github.com/intercom/claude-plugins/blob/main/plugins/base/docs/external-message-attribution.md)

[cathalging]

Approving. The point in my earlier comment is your call: fix it here or take it as a follow-up.

~ Automated via Claude (about: https://github.com/intercom/claude-plugins/blob/main/plugins/base/docs/external-message-attribution.md)

[yasser-aboelgheit-intercom]

Thanks for this. I checked it with the spec comparator, ref checks, and fern check (0 errors, same warnings as main), and checked each claim against how the API behaves.

A few questions:

1. Lookup order — Should the from descriptions say that email is used only when user_id isn't sent? The API tries id first, whatever the type. Next it tries user_id, then email, but only when no user_id was given. So type: lead with both user_id and email ignores the email and returns 404 "User Not Found". Something like "If you send more than one, id is used first, then user_id. email is used only when neither is sent."
2. multiple_users — This error (400) only happens when type is lead and email is the only identifier sent. With id or user_id as well, the request never returns it. Could the email description say so?
3. Dropping contact from from.type — This matches the API: from 2.6 a from.type of contact is treated as an admin. It returns 404 not_found with an id, or 400 parameter_invalid without one. But removing an enum value from 2.17, and from the Preview SDK's from.type, is a breaking schema change. Could someone who owns the public contract sign off before merge?

Holding approval until item 3 has that sign-off.

~ Automated via Claude

[yasser-aboelgheit-intercom]

Thanks for the follow-up. I re-ran the spec comparator, ref checks and fern check (0 errors, same warnings as main, no new unknown types in the Preview SDK), and rechecked the new wording against how the API behaves.

Resolved:

1. Lookup order — "id is used first, then user_id" and "email ... used only when user_id isn't sent" match the API. An id that doesn't match falls back to the other identifiers, and email is tried only when no user_id was given. This is more accurate than my earlier suggestion.
2. multiple_users — "If several leads share the email and it's the only identifier sent" matches the API. The 400 only happens when type is lead and neither id nor user_id is sent.

Nothing is wrong with the new wording.

Still open:

3. Dropping contact from from.type — Unchanged by this commit. Removing an enum value from 2.17, and from the Preview SDK from.type, is a breaking schema change. Could someone who owns the public contract sign off before merge?

Holding approval until item 3 has that sign-off.

~ Automated via Claude