What causes "Failed to add contact" in hcengineering/platform?

Verify the target phone number is a registered Telegram account and includes the country code

hcengineering/platform · error · Error

Failed to add contact

Error message

Failed to add contact

What it means

addContact() imports the contact into the user's Telegram account via contacts.importContacts; if the imported contacts list is empty, Telegram did not match any account and the contact cannot be added, so it throws.

Source

Thrown at services/telegram/pod-telegram/src/telegram.ts:310

    }

    return true
  }

  async addContact (contact: { phone: string, firstName: string, lastName: string }): Promise<void> {
    const result = await this.client.invoke(
      new Api.contacts.ImportContacts({
        contacts: [
          new Api.InputPhoneContact({
            ...contact,
            clientId: bigInt(0)
          })
        ]
      })
    )

    if (result.imported.length < 1) {
      throw Error('Failed to add contact')
    }
  }

  getToken (): string | undefined {
    // TODO: Need recheck
    // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
    return (this.client.session.save() as never as string) ?? undefined
  }
}

export type TelegramConnectionInterface = InstanceType<typeof TelegramConnection>

// Notice: not really elegant solution, for now have no better idea
// how to reorganize this mess. This helper works like buffer for connections
// that are not yet signed in and unified telegram connection creator.
export const telegram = new (class TelegramHelper {
  readonly conns = new Map<string, TelegramConnection>()
  readonly ttls = new Map<string, NodeJS.Timeout>()

View on GitHub (pinned to 63e28dc964)

Solutions

Verify the target phone number is a registered Telegram account and includes the country code
Normalize the phone number format (E.164) before addContact
Check whether the target is a bot/handle and use the appropriate messaging path instead
Catch the error and inform the user the contact could not be reached

Example fix

// before
await sendMessage(target) // throws 'Failed to add contact' for non-Telegram numbers
// after
const e164 = normalizeToE164(target)
if (!isRegisteredTelegramUser(e164)) {
  notify(`No Telegram account for ${e164}`)
  return
}
await sendMessage(e164)

Defensive patterns

Strategy: try-catch

Validate before calling

const e164 = normalizeToE164(phone)
if (!/^\+\d{7,15}$/.test(e164)) {
  throw new Error(`Invalid phone format: ${phone}`)
}

Type guard

function isValidPhone(v: unknown): v is string {
  return typeof v === 'string' && /^\+\d{7,15}$/.test(v)
}

Try / catch

try {
  await sendMessage(target)
} catch (err) {
  if (err.message === 'Failed to add contact') {
    notify(`Cannot reach ${target}: no Telegram account found`)
  }
}

Prevention

Normalize all phone numbers to E.164 before contact import
Check the target has a Telegram account before messaging
Handle bot/handle targets through a different path than phone contacts

When it happens

Trigger: sendMsg triggers addContact with a phone number that does not correspond to any Telegram user, or a malformed/incorrect phone value that Telegram cannot resolve.

Common situations: Messaging a phone number that never joined Telegram; storing phone numbers in the wrong format (missing country code); messaging bots or deleted accounts.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/2a1f6c8d3bf8e64b. Report an issue: GitHub.